是否可以在开放的 API 定义中 'group' 可重用组件？

Question

我正在学习使用 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'

我正在寻找一种方法来 'group' 它们，这样我就可以参考，例如，一条路径一次有 10 个不同的响应。这可能吗？我知道我可以参考所有响应，但我并不总是想为所有路径重用所有定义的代码。

Answer 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'

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

Answer 2

您可以在组件元素中使用默认响应。在此示例中，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

是否可以在开放的 API 定义中 'group' 可重用组件？

Is it possible to 'group' reusable components in open API definitions?

components

swagger

openapi