如何在Swagger Editor中配置二维数组类型的API入参

要生成你需要的http://localhost/api/catalog/product/list?filters[filter14][]=0格式请求，需根据你使用的OpenAPI版本（Swagger版本）来配置参数，以下是两种常用版本的实现方式：

OpenAPI 3.x（推荐） #

通过deepObject样式和explode配置实现嵌套数组参数的正确渲染，示例YAML代码如下：

openapi: 3.0.3
info:
  title: 产品列表API
  version: 1.0.0
paths:
  /api/catalog/product/list:
    get:
      summary: 获取产品列表
      parameters:
        - name: filters
          in: query
          required: false
          schema:
            type: object
            properties:
              filter14:
                type: array
                items:
                  type: integer
          style: deepObject
          explode: true

• style: deepObject：指定Swagger按照嵌套对象格式生成查询参数
• explode: true：将数组元素拆分为[key][]=value的形式，而非逗号分隔

配置完成后，Swagger UI会展示filters对象下的filter14数组输入框，输入值后将自动生成目标格式的请求URL。

Swagger 2.0（旧版本） #

如果使用的是Swagger 2.0规范，可直接指定带嵌套括号的参数名，并配合collectionFormat: multi实现：

swagger: '2.0'
info:
  title: 产品列表API
  version: 1.0.0
paths:
  /api/catalog/product/list:
    get:
      summary: 获取产品列表
      parameters:
        - name: filters[filter14]
          in: query
          required: false
          type: array
          items:
            type: integer
          collectionFormat: multi

• collectionFormat: multi：为数组的每个元素生成独立的filters[filter14][]=value参数项

内容的提问来源于stack exchange，提问作者Sergei Semenets