1

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

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?

4

1 回答 1

1

您可以使用共享responses对象来定义响应。然后在各个操作中引用它们。从关于共享响应对象的规范中：

一个对象，用于保存要跨操作重用的响应。响应定义可以参考此处定义的定义。

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

于 2015-11-13T15:12:47.653 回答