53

这个问题不是（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

4

2 回答 2

51

开放API 2.0

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

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

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


Swagger UI 用户注意：旧版本的 Swagger UI（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
于 2018-01-24T16:42:25.403 回答
-3

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

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

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

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

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

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

我确实理解没有明确允许/鼓励这样做（我也没有找到明确禁止它的地方）。但作为一种解决方法，并且是在当前规范中记录具有此行为的 API 的唯一方法，看起来像是一种选择。

我发现了两个问题：

  • Java 代码生成 URL 转义了“=”符号，因此除非您在生成的代码中修复此问题，否则它将无法工作。可能它发生在其他代码生成器中。
  • 如果您有更多查询参数，它将添加一个额外的“？” 失败；

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

于 2016-09-06T17:48:20.883 回答