如何使用 swagger 在路径中定义可选参数

Question

我的 REST Web 服务中有一个函数使用 GET 方法，它有两个可选参数。

我试图在 Swagger 中定义它，但在我将 required 设置为 false 后遇到错误，不是有效的参数定义。

我发现如果我将 required 值设置为 true，错误就会消失。这是我的 Swagger 代码示例。

...
paths:
  '/get/{param1}/{param2}':
    get:
      ...
      parameters:
      - name: param1
        in: path
        description: 'description regarding param1'
        required: false
        type: string
      - name: param2
        in: path
        description: 'description regarding param2'
        required: false
        type: string

我没有在 body 中的参数或查询中的参数中遇到过这种情况。我认为这个问题只与路径中的参数有关。我也无法在 swagger 规范文件中找到任何解决方案。

是否有任何其他方法可以在 Swagger 中定义可选参数，或者我的代码是否有任何错误？

如有任何帮助，我们将不胜感激。

Answer 1

它可能会爆炸，因为你不能有一个可选的基本 uri 参数，只能查询字符串值（在 url 的情况下）。

例如：

GET /products/{id}/pricing?foo=bar
** 如果 foo 是可选的，那么您的 IN 参数需要是 "query" 而不是 "path"
** 如果 {id} 是可选的，那么有问题。 {id} 不能是可选的，因为它包含在基本 uri 中。

这应该有效：

{
"in":"query",
"required":false
}

这应该行不通

{
"in":"path",
"required":false
}

将您的 "in" 属性更改为 "query" 而不是 "path"，它应该可以工作。

Answer 2

鉴于路径参数必须是必需的according to the OpenAPI/Swagger spec，您可以考虑添加 2 个具有以下路径的独立端点：

/get/{param1}/{param2} 提供param2时
/get/{param1}/ 没有提供param2时

Answer 3

您的 YAML 失败，因为正如规范中所述：

Determines whether this parameter is mandatory. If the parameter is in "path", this property is required and its value MUST be true.

来源：http://swagger.io/specification/#parameterObject（查看固定字段 table）

Answer 4

遗憾的是，在 2020 年和 3.* 规范中仍然没有对可选参数的官方支持： https://github.com/OAI/OpenAPI-Specification/issues/93

您只能应用其他答案中提到的一些解决方法（为每组参数描述几个端点；将您的 API 转换为使用查询参数而不是路径参数）。

我个人决定保持原样，只添加一个参数 description，它清楚地写着 "This parameter is OPTIONAL!"。每个阅读 API.

的人应该都清楚

Answer 5

尝试为同一个 API 添加 2 个端点。喜欢

/get/{param1}/{param2} 和 /get/{param1}/{param2}/{param3}

如何使用 swagger 在路径中定义可选参数

How to define an optional parameter in path using swagger

swagger

openapi