如何在Swagger（OpenAPI）中定义互斥查询参数？

我有一系列像这样的参数

“参数”：[
{
“名称”：“用户名”，
“说明”：“通过用户名/电子邮件获取用户名”，
“必需”：false，
“类型”：“字符串”，
“参数类型”：“查询”
},
{
“名称”：“站点”，
“说明”：“按站点获取用户名”，
“必需”：false，
“类型”：“字符串”，
“参数类型”：“查询”
},
{
“名称”：“调查”，
“说明”：“通过调查获取用户名”，
“必需”：false，
“类型”：“字符串”，
“参数类型”：“查询”
}
],

---

必须填写一个参数，但不管是哪个参数，其他参数可以留空。有没有办法用招摇来表达这一点？

不幸的是，这在目前是不可能的。“required”只是一个布尔值，无法表示参数之间的相互依赖关系

您所能做的最好的事情是在参数描述中明确需求，并在相同的行中加入定制的400错误请求描述

---

关于在下一版本的OpenAPI规范中实现这一点的可能方法，在上有一些讨论。

如何更改您的API设计？ 目前，您有一个方法，三个参数。若我理解得很好，那个么用户必须始终只提供一个参数，其余两个参数必须是未设置的

对我来说，API在三个端点（如

/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=

---

另一种方法是传入带有枚举的筛选器类型参数，以及带有要使用的值的筛选器值

例如：

---

它可以是必需的，也可以不是，由您选择。但是，如果需要一个参数，则它们都应该是。

在以下情况下，互斥参数是可能的（某种程度上）：

• 将互斥参数定义为对象属性，并使用

  oneOf

  或

  maxProperties

  将对象限制为仅1个属性
• 使用

  样式：form

  和

  分解：true

  ，以便将对象序列化为

  ？propName=value

使用

minProperties

和

maxperties

约束的示例：

openapi:3.0.0
...
路径：
/傅：
获取：
参数：
-in:查询
名称：过滤器
必填项：true
风格：形式
爆炸：真的
模式：
类型：对象
特性：
用户名：
类型：字符串
地点：
类型：字符串
调查：
类型：字符串
物业：1
maxProperties:1
附加属性：false

使用其中一个：

参数：
-in:查询
名称：过滤器
必填项：true
风格：形式
爆炸：真的
模式：
类型：对象
其中一项：
-特性：
用户名：
类型：字符串
必需：[用户名]
附加属性：false
-特性：
地点：
类型：字符串
必需：[站点]
附加属性：false
-特性：
调查：
类型：字符串
必需：[调查]
附加属性：false

使用之一的另一个版本：

参数：
-in:查询
名称：过滤器
必填项：true
风格：形式
爆炸：真的
模式：
类型：对象
特性：
用户名：
类型：字符串
地点：
类型：字符串
调查：
类型：字符串
附加属性：false
其中一项：
-必需：[用户名]
-必需：[站点]
-必需：[调查]

请注意，Swagger UI和Swagger Editor尚不支持上述示例（截至2018年3月）。似乎涵盖了参数渲染部分

---

OpenAPI规范存储库中也有一个开放的建议，因此规范的未来版本可能会有更好的方法来定义此类场景。

不幸的是，这项功能似乎无法解决技术问题，但不是非常Restful。我理解正确吗，在本例中，您的提案将产生API/用户？name=name&filterType=[name | site | survey]？我同意这一点，因为这更符合Restfull，因为我们有单一的资源，这是应该的（仍然有干净和可用的API）。OpenAPI 3.0有一种描述互斥参数的方法，请参阅。我是否遗漏了一些明显的东西？因为这似乎没有在aws的api上为我做任何验证gateway@omega_primeAWS API网关和一些其他OpenAPI功能。