是否可以在开放 API 定义中“分组”可重用组件？答案

【问题标题】：Is it possible to 'group' reusable components in open API definitions?是否可以在开放 API 定义中“分组”可重用组件？
【发布时间】：2021-03-17 13:34:20
【问题描述】：

我正在学习使用 swagger，但无法找到答案。

假设我有 10 个端点都共享一组响应，例如，假设它们是：

components:
  responses:
    'success':
      description: Success
    'failed':
      description: Failed
    'unknown':
      description: Unknown
    'dontincludeme':
      description: A status I don't always want to include

目前，据我了解，我需要在各种路径中引用它们如下：

paths:
  /start:
    post:
      summary: Start a process
      tags:
        - Process Management
      responses:
        '1':        
         $ref: '#/components/responses/success'
        '2':
         $ref: '#/components/responses/failed'
        '3':
         $ref: '#/components/responses/unknown'

我正在寻找一种将它们“分组”的方法，以便我可以一次引用 10 个不同的响应来获取路径。这可能吗？我知道我可以引用所有的响应，但我并不总是想为所有路径重用所有定义的代码。

【问题讨论】：

标签： components swagger openapi

【解决方案1】：

您可以对相同的响应 HTTP 状态代码分组不同的响应，如 OAS3 文档中的示例所示： https://swagger.io/docs/specification/describing-responses/

但我认为没有模板可以粘贴具有不同状态代码的响应集合。

     responses:
        '200':
          description: A JSON object containing pet information
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Cat'
                  - $ref: '#/components/schemas/Dog'
                  - $ref: '#/components/schemas/Hamster'

您可以更进一步，定义一个包含“oneOf”这些模式的组件 - 但您可能会开始失去可读性。

您可以考虑的另一个功能是同一文档中描述的默认响应。

     responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        # Definition of all error statuses
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

如果许多错误响应使用相同的架构，这将很有效。请注意，这不再记录服务器可能返回的特定错误代码 - 但仍为客户端提供编写通用错误处理程序的机会。

【讨论】：

【解决方案2】：

您可以在 components 元素中使用默认响应。在此示例中，200 代码特定于每个请求。 4xx 很常见

paths:    
    "/api/account":
        get:
          ...
          responses:
             200:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/user'
            400:
              $ref: '#/components/responses/BadRequest'
            401:
              $ref: '#/components/responses/Unauthorized'
            403:
              $ref: '#/components/responses/Forbidden'
    ...
components:
    responses:
       BadRequest:
         description: Bad Request
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Error'
       Unauthorized:
          description: Unauthorized
       Forbidden:
          description: Forbidden
       NotFound:
          description: The specified resource was not found
          content:
            application/json:
               schema:
                  $ref: '#/components/schemas/error'
       InternalError:
          description: Internal error

【讨论】：