Swagger 2.0 - 如何制作"一个或另一个"参数？

Question

我有一个下面定义的swagger 2.0资源.如何制作"param1或param2"？调用者必须传递param1或param2.

/some/res:
put:
  summary: some resource
  responses:
    200:
      description: Successful response
      schema:
        $ref: '#/definitions/SomeResponse'
  parameters:
    - name: param1
      type: string
      description: param1
      in: formData
      required: false
    - name: param2
      type: string
      description: param2
      in: formData
      required: false

Answer 1

OpenAPI(fka Swagger)规范不支持条件或互斥参数(任何类型).

有一个开放的功能请求:
支持查询参数之间的相互依赖性

Answer 2

在“ 描述参数 Swagger”文档的“参数依赖项”部分中：

Swagger不支持参数依赖性和互斥参数。在https://github.com/OAI/OpenAPI-Specification/issues/256上有一个开放功能请求。

截至2017年6月，该问题有21个投票，这是该项目中投票率第三高的问题。

Answer 3

可以使用OpenAPI 3.0和以下方法定义此问题中的特定情况– POST / PUT / PATCH请求的表单数据主体包含或param1或param2–oneOf

openapi: 3.0.0
...

paths:
  /some/res:
    put:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    param1:
                      type: string
                  required:
                    - param1
                  additionalProperties: false
                - type: object
                  properties:
                    param2:
                      type: string
                  required:
                    - param2
                  additionalProperties: false

Swagger UI用户注意事项：表单数据UI和oneOf模式的示例呈现尚不适用于OpenAPI 3.0定义。