如何在几乎所有路径中复制粘贴3个通用错误响应？

Question

我希望几乎所有路径都有以下3个通用错误响应。如何在Swagger中描述这一点，而不是在任何地方复制这些行？

    401:
      description: The requester is unauthorized.
      schema:
        $ref: '#/definitions/Error'
    500:
      description: "Something went wrong. It's server's fault."
      schema:
        $ref: '#/definitions/Error'
    503:
      description: Server is unavailable. Maybe there is maintenance?
      schema:
        $ref: '#/definitions/Error'

我在请求中如何使用它的示例：

paths:
    /roles:
      get:
        summary: Roles
        description: |
          Returns all roles available for users.
        responses:
          200:
            description: An array with all roles.
            schema:
              type: array
              items:
                $ref: '#/definitions/Role'
          401:
            description: The requester is unauthorized.
            schema:
              $ref: '#/definitions/Error'
          500:
            description: "Something went wrong. It's server's fault."
            schema:
              $ref: '#/definitions/Error'
          503:
            description: Server is unavailable. Maybe there is maintenance?
            schema:
              $ref: '#/definitions/Error'

Answer 1

看起来我可以添加以下全局响应定义：

# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
responses:
  NotAuthorized:
    description: The requester is unauthorized.
    schema:
      $ref: '#/definitions/Error'

但是我仍然需要在这样的路径中引用它：

401:
  $ref: '#/responses/NotAuthorized'

OpenAPI 3.0中的内容相同，只是它使用#/components/responses/...而不是#/responses/...：

openapi: 3.0.0

# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
components:
  responses:
    NotAuthorized:
      description: The requester is unauthorized.
      schema:
        $ref: '#/components/schemas/Error'

# Then, in operation responses, use:
...
401:
  $ref: '#/components/responses/NotAuthorized'

OpenAPI规范存储库中还有一个开放的feature request，用于添加对操作的全局/默认响应的支持。

Answer 2

看起来Open API specification不支持此功能。