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

【问题标题】：How to define an optional parameter in path using swagger如何使用 swagger 在路径中定义可选参数
【发布时间】：2021-11-14 17:04:47
【问题描述】：

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

我尝试在 Swagger 中定义它，但在将 required 设置为 false 后遇到错误，Not a valid parameter definition。

我发现如果我将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

我没有体验过正文中的参数或查询中的参数。我认为这个问题只与路径中的参数有关。我在 swagger 规范文件中也找不到任何解决方案。

有没有其他方法可以在 Swagger 中定义可选参数，或者我的代码有什么错误？

任何帮助将不胜感激。

【问题讨论】：

标签： swagger openapi

【解决方案1】：

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

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

【讨论】：

我来这里是为了寻找一个有点不同的问题的解决方案。使用 API Transformer 从 WADL 转换为 Swagger 时，我经常遇到这些错误。现在我通过添加两条单独的路线来手动解决这些问题。我正在寻找一种更好的转换器，它可以自动添加所有端点，而不是将 required 标记为 false 和失败。
@vezenkov 你试过github.com/lucybot/api-spec-converter 进行转换吗？
抱歉，您根本没有回答这个问题。如果确实不可能，请给出明确的答案It's not possible，如果需要，请给出替代方案。

【解决方案2】：

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

例如：

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

这应该可行：

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

这应该不起作用

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

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

【讨论】：

不幸的是，我认为您不能在“路径”中使用可选参数。这不是 Swagger 的事情，而是 URL 架构的工作方式。如果您有 GET /products/{id} 并且您说 {id} 是可选的，那么您已经完全更改了资源所针对的 url（即现在 GET /products）。也许你可以把这个带回给他们，问他们为什么要在基本 uri 中添加一个可选参数。我经常使用 REST API，这听起来像是需要更多考虑请求/资源来解决问题的情况。祝你好运！
如果我有以下端点，查询是否有效： /resource?querystring 和 /resource/{id} ？ {id} 可以与查询参数区分开来吗？
好吧，url 的最后一部分可以是可选的，不会破坏任何东西，没有这个参数你会得到列表，使用这个参数你会得到一个给定的项目。这是 Swagger 中的问题，而不是 Swagger 尝试记录的 Web API 中的问题。
这不起作用。 JSON 验证失败。

【解决方案3】：

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

确定此参数是否是必需的。如果参数在“路径”中，则此属性是必需的，其值必须为 true。

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

【讨论】：

【解决方案4】：

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

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

就我个人而言，我决定保留所有内容，只需添加一个参数description，它清楚地表明“此参数是可选的！”。对于阅读 API 的每个人来说都应该足够清楚。

【讨论】：

【解决方案5】：

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

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

【讨论】：