Swagger: cannot set "collectionFormat" - swagger

Question

A JSON query should be usable with multiple search parameters. For this, the server needs to get each parameter as search object, for example:
url/search=FirstParameter[EQ]foo&search=SecondParameter[EQ]bar
We use the following declaration in 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
The issue is, that the PHP library generated from swagger creates requests like this:
url/search=FirstParameter[EQ]foo&SecondParameter[EQ]bar
Which is not usable by server. To address this issue, i found that you could influence this behavior by setting the attribute "collectionFormat" not to multi but to csv.
My issue is, that declarations taken from the example page
https://swagger.io/docs/specification/2-0/describing-parameters/
do not work and display error:
should NOT have additional properties additionalProperty: collectionFormat
I've tried:
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
What could be the issue?

Answer 1

collectionFormat is an OpenAPI 2.0 keyword (i.e. used in swagger: "2.0"), but you seem to be using OpenAPI 3.0 (openapi: 3.0.x). The corresponding OAS3 keywords are style and explode, see the Parameter Serialization guide for details.
Try the following:
paths:
/url:
get:
parameters:
- in: query
name: search
description: |-
An array of strings like e.g. `person.nameLast[<operand>]value`
<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
Note that the requests will be sent with the [ and ] characters percent-encoded as %5B and %5D, because they are reserved characters according to RFC 3986.
url?search=FirstParameter%5BEQ%5Dfoo
The backend server is supposed to decode %5B...%5D back to [...]. (Any RFC-compliant server should do this automatically.)