Как определить параметры в квадратных скобках в OpenAPI (Swagger)?

У меня есть конечная точка с параметрами запроса, в которых используются квадратные скобки:

GET /info?sort[name]=1&sort[age]=-1

Здесь name и age - имена полей из моего определения модели.

Как я могу написать определение OpenAPI (Swagger) для этих параметров?


openapi swagger
person Alinex    schedule 28.01.2018    source источник

Ответы (1)


arrow_upward
10
arrow_downward

Это зависит от того, какую версию OpenAPI (Swagger) вы используете.

OpenAPI 3.0

Параметр sort может быть определен как объект со свойствами name и age. Параметр метод сериализации должен иметь значение style: deepObject и 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

Это поддерживается в Swagger UI 3.15.0+ и Swagger-Editor 3.5.6+.

OpenAPI 2.0 (Swagger 2.0)

sort[name] и sort[age] необходимо определить как отдельные параметры:

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
person Helen    schedule 29.01.2018