How to define parameters with square brackets in OpenAPI (Swagger)?
I have an endpoint with query parameters that use square brackets:
GET /info?sort[name]=1&sort[age]=-1
Here, name
and age
are the field names from my model definition.
How can I write an OpenAPI (Swagger) definition for these parameters?
It depends on which version of OpenAPI (Swagger) you use.
OpenAPI 3.x
The sort
parameter can be defined an an object with the name
and age
properties. The parameter serialization method should be style: deepObject
and explode: true
.
openapi: 3.0.0
...
paths:
/info:
get:
parameters:
- in: query
name: sort
schema:
type: object
properties:
name:
type: integer
example: 1
age:
type: integer
example: -1
style: deepObject
explode: true
responses:
'200':
description: OK
This is supported in Swagger UI 3.15.0+ and Swagger-Editor 3.5.6+.
Important: The deepObject
serialization style only supports simple non-nested objects with primitive properties, such as in the example above. The behavior for nested objects and arrays of objects is not defined.
In other words, while we can define
?param[foo]=...¶m[bar]=...
there's currently no way to define more nested query parameters such as
?param[0][foo]=...¶m[1][bar]=...
or
?param[foo][0][smth]=...&?param[foo][1][smth]=
If you need the syntax for deeply nested query parameters, upvote and follow this feature request:
Support deep objects for query parameters with deepObject style
OpenAPI 2.0 (Swagger 2.0)
sort[name]
and sort[age]
need to be defined as individual parameters:
swagger: '2.0'
...
paths:
/info:
get:
parameters:
- in: query
name: sort[name]
type: integer
- in: query
name: sort[age]
type: integer
responses:
200:
description: OK