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

Question

我正在用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(的字符串列表。我不明白为什么绳子爆炸了！非常感谢您的帮助。

Answer 1

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

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

• 调整后端代码，使其每隔一个逗号(而不是每个逗号(拆分接收到的sort字符串。

• 或者，对sort数组使用另一种序列化方法，例如：

  • 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"
  }