How to define parameters with square brackets in O

问题:

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?

回答1:

It depends on which version of OpenAPI (Swagger) you use.

OpenAPI 3.0

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+.

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