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

OpenAPI 3.0允许您使用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。

中口头记录这些细节

对于Swagger UI用户的注意事项：在撰写本文时（2018年12月），Swagger UI不会自动生成oneOf和anyOf架构的示例。您可以按this issue进行更新。

作为解决方法，您可以手动指定回复example。使用单个example，而不是多个examples（在Swagger UI中支持多个示例也是not available yet。）

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

Answer 2

我想要同样的事情，我想出了一个似乎有用的解决方法：

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

/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），以验证我是否遗漏了更多内容。

我确实明白不允许/鼓励这样做（我没有发现某个地方明确禁止它）。但作为一种解决方法，并且是在当前规范中使用此行为记录API的唯一方法，看起来像一个选项。

我发现了两个问题：

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

如果这些不是阻止程序，它至少会允许您正确记录此类情况并允许使用swagger编辑器进行测试。

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

2 个答案: