Swagger；基于可选参数指定两个具有相同代码的响应

Question

这个问题不是（Swagger-指定可选对象属性或多个响应）的重复，因为该OP试图返回200或400。

我有一个带有可选参数的GET；e、 例如，GET/endpoint？选择器=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

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

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

/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转义"="符号，因此它不会工作，除非您在生成的代码中修复此问题。可能它发生在其他代码生成器。
• 如果您有更多的查询参数，它将添加一个额外的？而失败；

如果这些不是拦截器，它至少可以让你正确地记录这样的情况，并允许用昂首阔步的编辑器进行测试。

Answer 2

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

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

但是，不可能将特定的响应模式映射到特定的参数值。您需要在响应、操作和/或参数的说明中口头记录这些细节。

这里可能有一个相关的增强请求：
允许使用get-^post-^etc重载operationObject


对于Swagger UI用户的注意事项：在撰写本文（2018年12月）时，Swagger UI不会自动为oneOf和anyOf模式生成示例。您可以关注此问题以获取更新。

作为一种解决方法，您可以手动指定响应示例或示例。请注意，使用多个示例需要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