斯威格2.0-如何使“一个或其他”参数的要求？

我在下面定义了一个炫耀的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
62364 次浏览
小开
最佳答案

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

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

小开

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

我建议在描述中清楚地说明包含/排除查询参数的规则。然后使用一个依赖于您的语言的验证框架(例如，javax.validfor Java，restify-validfor restify 等) ，相应地验证参数。

小开

在 参数描述 Swagger 文档的“参数依赖性”部分:

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

截至2017年6月，该期杂志有21个赞成票，成为该项目第三大赞成票最多的期刊。

小开

可以使用 OpenAPI 3.0和 oneOf定义这个问题中的特定场景——带有包含 param1或 param2的表单数据主体的 POST/PUT/PATCH 请求:

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 和用于 OpenAPI 3.0定义的 oneOf模式 不可用的示例呈现。

小开

你可以使用一个简单的技巧。使用具有相同路由的不同请求，但使用“ path”类型而不是“ query”定义不同的“自制”查询参数。 对于参数之间的一些相互依赖的逻辑，将逻辑放在 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

提交答案