我如何重构这个 Swagger API 规范

Question

我有几个端点，其中有一些标准错误响应，例如 404、401、403 和 default。我想将这些响应重构为 Swagger 定义，但我无法实现。我尝试了一些技巧，但总是导致解析错误。这是我的 yaml。

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 关于共享响应对象：

An object to hold responses to be reused across operations. Response definitions can be referenced to the ones defined here.

虽然这是一个有效的规范，但 Swagger-UI 将无法从 default 响应以外的共享响应中进行解析。这是与此相关的issue。