63

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

我试图在 Swagger 中定义它，但在我设置as后遇到错误Not a valid parameter definition。requiredfalse

我发现如果我将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 中定义可选参数，或者我的代码有什么错误？

任何帮助，将不胜感激。

4

5 回答 5

57

鉴于根据OpenAPI/Swagger规范必须需要 path 参数，您可以考虑添加具有以下路径的 2 个单独的端点：

  • /get/{param1}/{param2} 提供 param2 时
  • /get/{param1}/ 未提供 param2 时
于 2016-01-27T06:20:54.510 回答
26

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

例如：

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

这应该有效：

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

这不应该工作

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

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

于 2016-01-26T14:55:18.000 回答
5

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

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

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

于 2016-03-08T22:09:55.713 回答
3

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

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

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

于 2020-02-17T03:36:30.077 回答
1

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

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

于 2020-05-28T04:48:03.887 回答