在我的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我在body中的参数和query中的参数都没有遇到过这种情况。我认为这个问题只与路径中的参数有关。我在swagger规范文件中也找不到任何解决方案。
在Swagger中是否有其他方法来定义可选参数，或者我的代码中是否有任何错误？
如果你能帮忙的话，我将不胜感激。
6条答案
按热度按时间bpzcxfmw1#
根据 OpenAPI/Swagger 规范，path参数必须是必需的，您可以考虑使用以下路径添加2个单独的端点：
/get/{param1}/{param2}* 当提供param 2时 */get/{param1}/* 当未提供param 2时 *8gsdolmq2#
它可能会爆炸，因为你不能有一个基本的uri参数可选，只有查询字符串值（在url的情况下）。
举例来说：
***如果foo是可选的，那么你的IN参数需要是“query”而不是“path”。
***如果{id}是可选的，则说明有问题。{id}不能是可选的，因为它包含在基URI中。
这应该是可行的：
这应该行不通
将你的“in”属性改为“query”而不是“path”，这样就可以了。
q0qdq0h23#
可悲的是，但事实上，在2020年和3.* 规范中仍然没有对可选参数的官方支持：https://github.com/OAI/OpenAPI-Specification/issues/93
您只能应用其他答案中提到的一些变通方法（为每组参数描述几个端点;转换您的API以使用查询参数而不是路径参数）。
就我个人而言，我决定让一切保持原样，只是添加一个参数
description，它清楚地表明“这个参数是可选的！“。对于每个阅读API的人来说，应该足够清楚。yzxexxkh4#
你的YAML失败了，因为它在规范上说：
确定此参数是否为必填参数。如果参数在“path”中，则此属性是必需的，并且其值必须为true。
来源：http://swagger.io/specification/#parameterObject（查找 * 固定字段 * 表）
6tqwzwtp5#
尝试为同一个API添加2个端点。像
/get/{param1}/{param2}和/get/{param1}/{param2}/{param3}lnvxswe26#
在laravel或nelmio bundle for symfony works中：
@OA\Parameter（
name=“param2”，
description=“Param 2”，
in=“path”，
allowEmptyValue=true，
example=“1234”，
required=false，
我不知道如果在工程yaml的 Swagger 。但应该可以。