如何避免每个 api 路径重复 401 错误响应？ （开放API 3）

我在security和components/securitySchemes中定义了我的身份验证。 在有关 response 的 Swagger 文档中，他们提供了以下示例：

paths:
  /something:
    get:
      ...
      responses:
        ...
        '401':
           $ref: '#/components/responses/UnauthorizedError'
    post:
      ...
      responses:
        ...
        '401':
          $ref: '#/components/responses/UnauthorizedError'
...
components:
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string

我有比两条多得多的路径，要访问其中任何一条，必须对客户端进行身份验证。 我想避免为每个路径定义“401”，并在全局范围内定义一次，如果可能的话。

如何为每条路径使用此响应？

'401':
  $ref: '#/components/responses/UnauthorizedError'

如果您希望响应显示在该特定端点上，则不能。

我通过不将重要错误添加到每个端点，而是将易于理解的标准响应（401、403、429、404、503）放在状态端点或根方法上来避免重复出现有利于重要错误的错误。 例如：

  '/{foo}/{bar}/status':
    get:
      tags:
        - api
      responses:
        '200':
          description: successful response with a resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/statusResponse'
        '400':
          $ref: '#/components/responses/400_error_response'
        '401':
          $ref: '#/components/responses/401_error_response'
        '403':
          $ref: '#/components/responses/403_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'          
        '500':
          $ref: '#/components/responses/500_error_response'

然后，样板响应将全部引用标准响应。

然后，实际端点通常具有特定于该操作的明确定义的响应以及可能 go 特别错误的事情。

  '/{foo}/{bar}/segment':
    post:
      summary: checks username is found or not
      description: |-
        checks username and returns 204 if found else 403
      operationId: checkUsername
      tags:
        - Login
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/segment_POST_request'
      responses:
        '200':
          $ref: '#/components/responses/segment_POST_200_response'
        '403':
          $ref: '#/components/responses/403_forbidden_response'
        '500':
          $ref: 
 '#/components/responses/500_internal_server_error_replayable_response'

我确保的一件事是错误响应，该操作的可能错误代码包含在响应中，如下所示：

    500_internal_server_error_replayable_response:
      description: |-
        The following `500 Internal Server Error` errors can occur during the API processing.
        
        | errorCode | cause | details |
        | - | - | - |
        | `SOME.ERROR.500` | There was an error processing the request either in Foo or on a downstream system | A request to something failed, Bar or Baz however the error is recoverable and can be replayed |
        | `SOME.ERROR.014` | Baz returned a `404` during the migration operation, even though it has previously confirmed the member exists | This is a fatal error during the migration process and cannot be recovered. The request should not be replayed. |
      headers:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            status: '500'
            errorCode: SOME.ERROR.500
            errorDescription: The request could not be processed
            errorSubCode: ''
            furtherDetails: ''
            docLink: ''     

使用扩展将它们作为构建脚本的一部分自动添加。

您要做的不是 OpenAPI 标准的一部分。 响应不是从父对象继承的； 它们必须显式添加到每个端点。 您可以为每个响应包含一个$ref ，但是使用具有许多端点的定义明确的规范，您最终会得到很多重复，并且随着时间的推移，端点可能会错过一两个响应作为添加和修改被制作。 另外，这根本不是一个好的创作体验。

为防止出现此问题，请在您的回复中添加扩展名，如下所示：

responses:
  x-default-responses: true
  '418':
    description: Additional responses go here

上述规范将是您使用的规范。 完成后，让脚本扫描您完成的 yaml 文件，并将该行替换为您的默认响应列表。 将此修改后的规范用作开发过程的下一阶段（无论您使用 OpenAPI 规范做什么，无论是文档、测试还是 SDK 生成）。

虽然您可以让脚本添加没有扩展属性的响应（毕竟，您正在编写的只是 YAML），但我建议您不要这样做。 该扩展使您的意图清晰，因此其他编辑将了解存在的其他响应。 此外，很可能（现在或将来的某一天）您将拥有不符合默认响应的端点，因此您不希望意外添加这些端点。