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（披露：我写过）和OpenAPI Specification。

避免在Swagger 2.0中使用样板

1 个答案: