Swagger配置array类型查询参数时collectionFormat属性报错问题咨询

• 属性放置位置不符合Swagger规范

如果你使用的是Swagger 2.0版本，collectionFormat属于参数级配置项，需要直接写在searchParam的根层级下，不能嵌套在schema字段内部。你将它放到了schema结构中，就会触发「不允许额外属性」的校验错误。

• 版本不兼容导致属性无效

如果你使用的是OpenAPI 3.x（即Swagger 3.0及以上版本），collectionFormat属性已经被官方废弃，该版本改用style+explode两个配置项来控制参数序列化格式，所以你写collectionFormat会被识别为非法额外属性。

另外补充：你的调研结论存在偏差，collectionFormat: csv对应的序列化格式是单参数逗号分隔，即search=FirstParameter[EQ]foo,SecondParameter[EQ]bar，只有对应配置的multi格式才能生成你预期的search=xxx&search=yyy格式。

Swagger 2.0版本配置 #

parameters:
searchParam:
  description: |
    array of strings like e.g. person.nameLast[<operand>]Bur<br>
    <operands> := LEQ, LT, EQ, GT, GEQ, LIKE
  name: search
  in: query
  type: array
  collectionFormat: multi
  items:
    minItems: 1
    type: string
  writeOnly: true

OpenAPI 3.x版本配置 #

parameters:
searchParam:
  description: |
    array of strings like e.g. person.nameLast[<operand>]Bur<br>
    <operands> := LEQ, LT, EQ, GT, GEQ, LIKE
  name: search
  in: query
  style: form
  explode: true
  schema:
    type: array
    writeOnly: true
    items:
      minItems: 1
      type: string

内容的提问来源于stack exchange，提问作者snx