Как мне реорганизовать эту спецификацию API Swagger

У меня есть несколько конечных точек, где у меня есть стандартные ответы об ошибках, такие как 404, 401, 403 и default. Я хочу преобразовать эти ответы в определение Swagger, но я не могу этого добиться. Я пробовал несколько трюков, но это всегда приводило к ошибкам синтаксического анализа. Вот ямл, который у меня есть.

swagger: '2.0'
info:
  title: My API
  description: My API description
  version: 0.0.1
host: api.example.com
schemes:
  - https
basePath: /
produces:
  - application/json
paths:
  /users:
    get:
      operationId: getUsers
      summary: Get users
      description: Get all users
      tags:
        - Users
      responses:
        '200':
          description: An array of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        '401':
          description: Authentication required
          schema:
            $ref: '#/definitions/Error'
        '402':
          description: Payment required
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Unauthorized access
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /games:
    get:
      operationId: getGames
      summary: Get games
      description: Get all games
      tags:
        - Games
      responses:
        '200':
          description: An array of games
          schema:
            type: array
            items:
              $ref: '#/definitions/Game'
        '401':
          description: Authentication required
          schema:
            $ref: '#/definitions/Error'
        '402':
          description: Payment required
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Unauthorized access
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        description: Unique id of user
      name:
        type: string
        description: Name of user
  Game:
    type: object
    properties:
      id:
        type: integer
        description: Unique id of game
      name:
        type: string
        description: Name of game
  Error:
    type: object
    properties:
      code:
        type: integer
        description: HTTP status code
      message:
        type: string
        description: Message describing error

Обратите внимание на повторяющиеся ответы в /users и /games. Как мне провести рефакторинг и переместить их в definitions?


person Kulbir Saini    schedule 13.11.2015    source источник


Ответы (1)


Вы можете использовать общий объект responses для определения ответов. Затем направьте их в отдельные операции. Из spec об объекте общих ответов:

Объект для хранения ответов для повторного использования в операциях. Определения ответов можно сослаться на определения, определенные здесь.

Хотя это будет допустимой спецификацией, Swagger-UI не сможет анализировать общие ответы, кроме ответа default. Вот проблема, связанная с этим.

person hassansin    schedule 13.11.2015
comment
На самом деле это не решает проблему эффективно. Я искал что-то, где я могу определить объект, скажем, ApiErrors со свойствами, такими как 401, 402 и т. д., и наследовать этот объект под responses для определенного запроса. - person Kulbir Saini; 13.11.2015
comment
afaik, это невозможно с текущей спецификацией. - person hassansin; 14.11.2015
comment
да похоже дело в этом. Принятие ответа как наилучшего сценария на данный момент. - person Kulbir Saini; 14.11.2015