如何避免每個 api 路徑重復 401 錯誤響應？ （開放API 3）

Question

我在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'

Answer 1

如果您希望響應顯示在該特定端點上，則不能。

我通過不將重要錯誤添加到每個端點，而是將易於理解的標准響應（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: ''     

Answer 2

使用擴展將它們作為構建腳本的一部分自動添加。

您要做的不是 OpenAPI 標准的一部分。 響應不是從父對象繼承的； 它們必須顯式添加到每個端點。 您可以為每個響應包含一個$ref ，但是使用具有許多端點的定義明確的規范，您最終會得到很多重復，並且隨着時間的推移，端點可能會錯過一兩個響應作為添加和修改被制作。 另外，這根本不是一個好的創作體驗。

為防止出現此問題，請在您的回復中添加擴展名，如下所示：

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

上述規范將是您使用的規范。 完成后，讓腳本掃描您完成的 yaml 文件，並將該行替換為您的默認響應列表。 將此修改后的規范用作開發過程的下一階段（無論您使用 OpenAPI 規范做什么，無論是文檔、測試還是 SDK 生成）。

雖然您可以讓腳本添加沒有擴展屬性的響應（畢竟，您正在編寫的只是 YAML），但我建議您不要這樣做。 該擴展使您的意圖清晰，因此其他編輯將了解存在的其他響應。 此外，很可能（現在或將來的某一天）您將擁有不符合默認響應的端點，因此您不希望意外添加這些端點。