避免在 Swagger 2.0 中使用样板代码

Question

我的 API 遵循常规状态代码，我发现自己在 api 定义的响应部分重复相同的文本

404:
          description: The resource doesn't exist
          schema:
            $ref:   '#/definitions/Error'
default:
          description: An unexpected error has occurred
          schema:
            $ref:   '#/definitions/Error'

我也遇到过类似的问题，就是无法分解出枚举属性和参数。我的 Swagger 代码可以变得更干吗？

Answer 1

是的，您的代码可能会变得更加枯燥：OpenAPI (fka.Swagger) 规范提供了许多分解事物的方法，包括响应、参数和枚举。

可重复使用的回复

您几乎可以像在示例中定义 Error 一样定义可重用响应。

首先添加响应，例如 Standard404，根级别 responses 中的定义

responses:
  Standard404:
    description: The resource doesn't exist
    schema:
      $ref: '#/definitions/Error'

然后，将它与 $ref : '#/responses/Standard404' 一起用于 responses 中的任何操作的 404 状态代码

responses:
  404:
    $ref: '#/responses/Standard404'

可重复使用的参数

对于可重用的参数，也是一样的。

首先添加一个参数，例如ID，定义在parameters根级：

parameters:
  ID:
    name: id
    in: path
    required: true
    type: string

然后在带有 $ref: '#/parameters/ID' 的任何参数列表中使用它。 专业提示：参数可以在操作级别定义，也可以在路径级别定义：

  /other-resources/{id}:
    get:
      parameters:
        - $ref: '#/parameters/ID'

 /resources/{id}:
    parameters:
      - $ref: '#/parameters/ID'

可重用枚举

你需要做的就是用枚举定义一个字符串类型（或整数或数字）的定义：

SomeValueWithEnum:
    type: string
    enum:
      - a value
      - another value

然后像这样多次使用它：

 Resource:
    properties:
      dummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

完整示例

下面是这 3 个用例的完整示例：

swagger: '2.0'

info:
  version: 1.0.0
  title: API
  description: Reusable things example

paths:

  /resources:
    post:
      responses:
        200:
          description: OK
        default:
          $ref: '#/responses/Default'

  /resources/{id}:
    parameters:
      - $ref: '#/parameters/ID'
    get:
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'
    delete:
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'

  /other-resources/{id}:
    get:
      parameters:
        - $ref: '#/parameters/ID'
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'

definitions:
  Error:
    properties:
      message:
        type: string

  SomeValueWithEnum:
    type: string
    enum:
      - a value
      - another value

  Resource:
    properties:
      dummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

  AnotherResource:
    properties:
      anotherDummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

parameters:
  ID:
    name: id
    in: path
    required: true
    type: string

responses:
  Standard404:
    description: The resource doesn't exist
    schema:
      $ref: '#/definitions/Error'
  Default:
    description: An unexpected error has occurred
    schema:
      $ref:   '#/definitions/Error'

更多相关信息 你应该阅读这个 tutorial (disclosure: I wrote it) and the OpenAPI Specification.

避免在 Swagger 2.0 中使用样板代码

Avoid boilerplate in Swagger 2.0

swagger

swagger-2.0