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

Posted 2023-03-28

技术标签:

【中文标题】如何使用 swagger 在路径中定义可选参数【英文标题】：How to define an optional parameter in path using 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 中定义可选参数，或者我的代码有什么错误？

任何帮助将不胜感激。

【问题讨论】：

【参考方案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 失败，因为正如规范中所述：