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

Question

此问题不是(Swagger - 指定可选对象属性或多个响应)的重复,因为该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模式.您可以按照此问题进行更新.

作为解决方法,您可以example手动指定响应.使用单个examples而不是多个examples(在Swagger UI中也不支持多个示例).

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