URL 查询参数中对象数组的 Swagger/OpenAPI 规范

Question

假设我有一个采用以下路径的 URL:?filter[id]=1&filter[name]=bob&order[][name]=asc&order[][age]=desc

如何将其转换为 swagger 文档，特别是对象数组和数组作为查询参数。

Answer 1

您的示例不是对象的数组，而是两个单独的对象参数 - filter 和 order[]，每个都使用 deepObject 样式序列化(在 OpenAPI 3.0 中受支持)。您可以如下描述这些参数:

openapi: 3.0.2
...

paths:
  /something:
    get:
      # ?filter[id]=1&filter[name]=bob&order[][name]=asc&order[][age]=desc
      parameters:
        - in: query
          name: filter
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: bob
          style: deepObject

        - in: query
          name: order[]
          schema:
            type: object
            properties:
              name:
                type: string
                example: asc
              age:
                type: string
                example: desc
          style: deepObject