Как реорганизовать этот API Swagger API

Question

У меня есть несколько конечных точек, где у меня есть некоторые стандартные ответы об ошибках, такие как 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?

Answer 1

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

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

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