如何在OpenAPI（Swagger）中使用方括号定义参数？

Question

我有一个具有使用方括号的查询参数的端点：

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

这里，name和age是我模型定义中的字段名。

我该如何为这些参数编写OpenAPI（Swagger）定义？

- Alinex

Answer 1

这取决于您使用的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]=...&param[bar]=...

目前没有办法定义更多嵌套的查询参数，比如

?param[0][foo]=...&param[1][bar]=...
or
?param[foo][0][smth]=...&?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

- Helen