openapi，字符串列表作为查询参数答案

【问题标题】：openapi, list of strings as query parameteropenapi，字符串列表作为查询参数
【发布时间】：2022-01-23 04:00:02
【问题描述】：

我在定义一个查询参数，用openapi 3.0.1，如下

{
  "name" : "sort",
  "in" : "query",
  "description" : "Sorting criteria. Example: productCode,desc",
  "required" : false,
  "explode" : false,
  "schema" : {
    "type" : "array",
    "items" : {
      "type" : "string"
    }
  }
}

如果我添加两个字符串，则在 swagger-ui 3.51.1 上

"parameter1,asc"
"parameter2,desc"

它们被正确序列化（作为具有 2 个元素的字符串列表），但如果我只添加一个字符串

"parameter1,asc"

它将被错误地序列化为具有 2 个元素（parameter1 和 asc）的字符串列表。我不明白为什么字符串会爆炸！非常感谢任何帮助。

【问题讨论】：

标签： swagger swagger-ui openapi

【解决方案1】：

在您的示例中，查询参数没有定义style，因此默认为style: form。非分解形式样式将逗号 , 视为数组项的分隔符。这会导致歧义，因为您的数组项的值也使用逗号作为内部分隔符。

可能的解决方案涉及更改后端代码和/或 OpenAPI 参数定义。

调整后端代码，使其将接收到的sort 字符串每隔一个逗号而不是每个逗号分割一次。
或者，为sort 数组使用另一个serialization method，例如：
- explode: true发送爆炸数组：
```
?sort=parameter1,asc&sort=parameter2,desc
```
- style: pipeDelimited + explode: false 使用| 而不是逗号分隔数组项：
```
?sort=parameter1,asc|parameter2,desc
```

或者，将sort 更改为对象/映射而不是数组：

{
  "name": "sort",
  "in": "query",
  "description": "Sorting criteria. Example: productCode,desc",
  "required": false,
  "explode": false,
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string",
      "enum": ["asc", "desc"]
    }
  }
}

在这种情况下，您当前的查询字符串格式

?sort=parameter1,asc,parameter2,desc

明确对应：

{
  "parameter1": "asc",
  "parameter2": "desc"
}

【讨论】：