Избежать шаблонного в Форс 2.0

Мои API уважают обычные коды состояния, и я обнаружил, что повторяю тот же текст в части ответов моего определения api 

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

Аналогичная проблема, с которой я также сталкиваюсь, заключается в том, что я не могу разложить на множители свойства и параметры перечисления. Может ли мой Свэггер-код стать более сухим?

1 3
swagger-2.0

1 ответ:

Да, ваш код может стать гораздо более сухим: OpenAPI (fka. Спецификация Swagger) предлагает множество способов факторинга вещей, включая ответы, параметры и перечисления.

Многоразовые ответы

Вы можете определить повторно используемый ответ почти так же, как вы определили Errorв своем примере.

Сначала добавьте ответ, например Standard404, определение в responses на корневом уровне 

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

Затем используйте его с $ref : '#/responses/Standard404' для 404 кода состояния в responses на любом операция 

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

Многоразовые параметры

Для повторно используемых параметров это одно и то же.

Сначала добавьте параметр, например ID, определение в parameters на корневом уровне: 

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

Затем используйте его в любом списке параметров с $ref: '#/parameters/ID'. Pro tip : параметры могут быть определены на уровне операции, но также и на уровне пути: 

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

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

Многоразовые перечисления

Все, что вам нужно сделать, это определить определение типа string (или целое число или число) с перечислением: 

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'

Подробнее об этом Вы должны прочитать этот учебник (раскрытие: я написал его) и спецификацию OpenAPI.

4