Swagger 2.0 - 如何使“一个或另一个”参数成为必需？

Posted 2023-02-16

【中文标题】Swagger 2.0 - 如何使“一个或另一个”参数成为必需？

【英文标题】：Swagger 2.0 - how to make "one or the other" parameter required?

【发布时间】：2015-06-24 20:29:43

【问题描述】：

我在下面定义了一个 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

【问题讨论】：

相关（或重复）：How to define mutually exclusive query parameters in Swagger (OpenAPI)?

【参考方案1】：

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

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

【参考方案2】：

Swagger 规范不支持条件要求或参数的包含/排除。

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

【参考方案3】：

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

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

截至 2017 年 6 月，该问题获得了 21 次投票，成为该项目中投票次数第三多的问题。

【参考方案4】：

这个问题的具体场景——一个包含param1或param2的表单数据主体的POST/PUT/PATCH请求——可以使用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 定义。

【讨论】：

对查询参数而不是正文模式使用oneOf 怎么样？我猜这仍然不受支持？

@hris.to 我不确定，如果没有看到实际规格很难说。如果 Swagger UI 中出现问题，我建议您在此处提交问题：github.com/swagger-api/swagger-ui/issues

【参考方案5】：

您可以使用一个简单的技巧。使用具有相同路由的不同请求，但使用“路径”类型而不是“查询”定义不同的“自制”查询参数。 对于参数之间的一些相互依赖的逻辑，将逻辑放在你的 API 中，并根据正确/不正确的请求定义特定的响应。您还可以在客户端保护 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