Блог

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

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

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

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

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

OpenAPI 3.x

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 .

Важно: deepObject стиль сериализации поддерживает только простые не вложенные объекты с примитивными свойствами, такими как в примере выше. Поведение для вложенных объектов и массивов объектов не определено.

Другими словами, пока мы можем определить

 ?param[foo]=...amp;param[bar]=...
 

в настоящее время нет способа определить дополнительные вложенные параметры запроса, такие как

 ?param[0][foo]=...amp;param[1][bar]=...
or
?param[foo][0][smth]=...amp;?param[foo][1][smth]=
 

Если вам нужен синтаксис для глубоко вложенных параметров запроса, проголосуйте и выполните этот запрос функции:
Поддержка глубоких объектов для параметров запроса со стилем deepObject

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