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

Question

此问题与 ( Swagger - Specify Optional Object Property or Multiple Responses ) 不重复，因为该 OP 试图返回 200 或 400。

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

我想返回一个 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

开放API 2.0

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

开放API 3.0

在 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 中口头记录这些细节。响应、操作和/或参数。

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

Swagger UI 用户注意事项:在撰写本文时(2018 年 12 月)Swagger UI 不会自动为 oneOf 生成示例和 anyOf模式。您可以关注 this issue更新。

作为解决方法，您可以指定响应 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:   # <--------
                foo: bar