Swagger:无法设置“collectionFormat”

Question

JSON查询应该可以使用多个搜索参数。为此，服务器需要获取每个参数作为搜索对象，例如:

url/search=FirstParameter[EQ]foo&search=SecondParameter[EQ]bar

我们在swagger中使用下面的声明:

 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
  schema:
    type: array
    writeOnly: true
    items:
      minItems: 1
      type: string

问题是，从swagger生成的PHP库创建的请求如下：

url/search=FirstParameter[EQ]foo&SecondParameter[EQ]bar

这是服务器无法使用的。为了解决这个问题，我发现可以通过将属性“collectionFormat”设置为csv而不是multi来影响这个行为。

我的问题是，声明取自示例页面https://swagger.io/docs/specification/2-0/describing-parameters/

不工作并显示错误：

不应具有附加属性additionalProperty:collectionFormat

我试过了：

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
  schema:
    type: array
    collectionFormat: csv
    writeOnly: true
    items:
      minItems: 1
      type: string

问题可能是什么？

Answer 1

collectionFormat是一个OpenAPI 2.0关键字（即在swagger中使用：“2.0”），但你似乎正在使用OpenAPI 3.0（openapi：3.0.x）。对应的 OAS3 关键字为样式和分解，有关详细信息，请参阅参数序列化指南。

尝试以下操作：

paths:
  /url:
    get:
      parameters:
        - in: query
          name: search
          description: |-
            An array of strings like e.g. `person.nameLast[<operand>]value`
            
            &lt;operand> can be: LEQ, LT, EQ, GT, GEQ, LIKE

          schema:
            type: array
            minItems: 1   # This keyword must be on the same level as `type: array`
            items:
              type: string

          # Optional example
          example:
            - FirstParameter[EQ]foo
            - SecondParameter[EQ]bar

          # This is the default serialization style for query parameters
          # so you can omit these keywords if you wish
          style: form
          explode: true

请注意，发送请求时会将< code>[和< code>]字符百分比编码为< code>[和< code>]，因为根据RFC 3986，它们是保留字符。

url?search=FirstParameter%5BEQ%5Dfoo

后端服务器应该将＜code＞〔…〕