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

Question

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

我尝试在Swagger中定义它但在设置as 后遇到错误,不是有效的参数定义.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

我没有使用body中的参数或查询中的参数来体验这一点.我认为这个问题只与路径中的参数有关.我也无法在swagger规范文件中找到任何解决方案.

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

任何帮助,将不胜感激.

Answer 1

鉴于必须根据OpenAPI/Swagger规范要求路径参数,您可以考虑使用以下路径添加2个单独的端点:

• /get/{param1}/{param2} 当提供param2时
• /get/{param1}/ 什么时候没有提供param2

Answer 2

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

例如:

• GET/products/{id}/pricing？foo = bar
• **如果foo是可选的,那么你的IN参数需要是"查询"而不是"路径"
• **如果{id}是可选的,则出现问题.{id}不能是可选的,因为它包含在基础uri中.

这应该工作:

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

这应该不起作用

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

将您的"in"属性更改为"查询"而不是"路径",它应该有效.

Answer 3

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

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

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

Answer 4

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

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

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