首页 文章

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

提问于
浏览 次
21

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

swagger swagger-2.0

2 回答

  • 11

    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'

    但是，'s not possible to map specific responses to specific parameter values. You'需要在 description 中口头记录这些细节 .

    Note for Swagger UI users: 撰写本文时（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
    回复于
  • 2

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

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

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

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

    路径在swagger编辑器上工作 . 我甚至可以以不同的方式记录每个选项，并将可选参数放在第二个案例中，这使得API doc更加清晰 . 使用operationId可以为生成的API方法生成更清晰的名称 .

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

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

    我发现了两个问题：

    • Java代码生成URL转义"="符号，因此除非您在生成的代码中修复此问题，否则它将无法运行 . 可能它发生在其他代码生成器中 .

    • 如果你有更多的查询参数，它会添加一个额外的"?"并失败;

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

    回复于

相关问题