Swagger 2.0 - 如何使 "one or the other" 参数成为必需的？

Question

我在下面定义了一个 swagger 2.0 资源。我怎样才能使 "param1 or 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) 规范不支持条件或互斥参数（任何类型）。

有一个开放的功能请求：
Support interdependencies between query parameters

Answer 2

Swagger 规范不支持条件要求或 inclusion/exclusion 参数。

我的建议是在描述中明确说明您对 inclusion/exclusion 查询参数的规则。然后使用取决于您的语言的验证框架（即 javax.validation 用于 Java，restify-validation 用于 restify 等），相应地验证参数。

Answer 3

在 Describing Parameters Swagger 文档的参数依赖项部分：

Swagger does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256.

截至 2017 年 6 月，该问题获得了 21 个赞成票，使其成为该项目中第三大获得赞成票的问题。

Answer 4

这个问题中的特定场景——POST/PUT/PATCH 请求的表单数据主体包含 param1 或 param2——可以使用 OpenAPI 3.0 和 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 模式的示例呈现 are not available 尚未用于 OpenAPI 3.0 定义。

Answer 5

你可以使用一个简单的技巧。使用具有相同路由的不同请求，但使用“路径”类型而不是“查询”定义不同的“自制”查询参数。对于参数之间的一些相互依赖的逻辑，将逻辑放在你的 API 中，并根据 correct/uncorrect 请求定义特定的响应。您还可以在客户端保护 URL 定义，但让它们所属的东西。

/myUrl/myRoute/?queryPara1={query1}?queryPara2={query2}:
get:
  parameters:
    - in: path
      name: query1
      schema:
        type: string
    - in: path
      name: query2
      schema:
        type: string 

/myUrl/myRoute/?queryPara3={query3}?queryPara4={query4}:
get:
  parameters:
    - in: path
      name: query3
      schema:
        type: string
    - in: path
      name: query4
      schema:
        type: string

Swagger 2.0 - 如何使 "one or the other" 参数成为必需的？

Swagger 2.0 - how to make "one or the other" parameter required?

swagger