昂首阔步;根据可选参数指定具有相同代码的两个响应

Question

这个问题不是 () 的重复问题，因为那个 OP 试图 return 200 或 400。

我有一个带有可选参数的 GET；例如，GET /endpoint?selector=foo。

我想 return 一个 200，其模式根据是否传递参数而不同，例如：

GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah  -> {200, schema_2}

在 yaml 中，我尝试使用两个 200 代码，但查看器将它们压扁，就好像我只指定了一个。

有办法吗？

编辑：以下似乎相关：https://github.com/OAI/OpenAPI-Specification/issues/270

Answer 1

我想要同样的东西，我想出了一个似乎有效的解决方法：

我刚刚定义了两个不同的路径：

/path:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseOne'
(...)

/path?parameter=value:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseTwo'
(...)

路径在 swagger 编辑器上有效。我什至可以以不同的方式记录每个选项，并将仅可能出现在第二种情况下的可选参数放在一起，使 API 文档更加清晰。使用 operationId，您可以为生成的 API 方法生成更清晰的名称。

我在此处发布了相同的解决方案 (https://github.com/OAI/OpenAPI-Specification/issues/270) 以验证我是否遗漏了更多内容。

我明白这不是明确的 allowed/encouraged 去做（我也没有找到明确禁止这样做的地方）。但作为一种解决方法，并且是在当前规范中记录具有此行为的 API 的唯一方法，看起来像是一个选项。

我发现了两个问题：

Java code gen URL 转义了“=”符号，因此它不会工作，除非您在生成的代码中修复此问题。可能它发生在其他代码中发电机。
如果你有更多的查询参数，它会添加一个额外的“？”失败了；

如果这些不是障碍，它至少可以让您正确记录此类情况并允许使用 swagger 编辑器进行测试。

Answer 2

OpenAPI 2.0

OAS2 不支持每个状态代码的多个响应模式。您只能有一个模式，例如，一个自由格式的对象（type: object 没有 properties）。

OpenAPI 3.x

在 OAS3 中，您可以使用 oneOf 为同一操作定义多个可能的请求主体或响应主体：

openapi: 3.0.0
...
paths:
  /path:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'

但是，无法将特定的响应模式映射到特定的参数值。您需要在响应的 description 中口头记录这些细节，操作and/or参数。

这是一个可能相关的增强请求：
Allow operationObject overloading with get-^ post-^ etc

Swagger UI 用户注意事项：旧版本的 Swagger UI（v.3.39.0 之前）不会自动为 oneOf 和 anyOf 模式。作为解决方法，您可以手动指定响应 example 或 examples。请注意，使用多个 examples 需要 Swagger UI 3.23.0+ 或 Swagger Editor 3.6.31+.

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'
              example:   # <--- Workaround for Swagger UI < 3.39.0
                foo: bar

昂首阔步;根据可选参数指定具有相同代码的两个响应

Swagger; specify two responses with same code based on optional parameter

swagger

swagger-2.0

openapi

OpenAPI 2.0

OpenAPI 3.x