Swagger中Array[]类型参数的描述与Swagger UI传参问题咨询

嘿，我来帮你搞定这两个Swagger数组参数的问题，我之前做接口文档的时候也踩过类似的坑，分享下实际能用的解决方法：

Swagger（现在常说的OpenAPI）不同版本的写法略有区别，分两种情况给你举例：

OpenAPI 3.x（推荐使用的新版本） #

不管参数是在query、path还是requestBody里，都用schema.type: array配合items指定数组元素的类型：

• Query/Path参数示例：

parameters:
  - name: user_ids
    in: query
    description: 需要查询的用户ID列表
    required: true
    schema:
      type: array
      items:
        type: integer # 数组元素为整数类型
      example: [1001, 1002, 1003] # 提供示例方便理解

• RequestBody里的数组示例：

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: array
        items:
          type: string
          example: ["admin", "editor", "viewer"] # 元素为字符串类型的数组

Swagger 2.0（旧版本） #

写法上会用type: array加items，另外需要用collectionFormat指定数组的序列化格式：

parameters:
  - name: tags
    in: query
    type: array
    items:
      type: string
    collectionFormat: csv # 可选值还有multi、ssv、tsv等，对应不同分隔方式
    required: true

这个问题的核心是Swagger配置的数组格式要和后端接口期望的解析方式一致，不然传参肯定会失败，我分版本和操作步骤给你说明：

先看配置（决定UI里的传参方式） #

OpenAPI 3.x #

用style和explode两个属性控制数组的序列化方式：

• 逗号分隔格式（csv）：适合后端期望ids=1,2,3这种形式

parameters:
  - name: ids
    in: query
    schema:
      type: array
      items:
        type: integer
    style: form
    explode: false # 关键：设为false会把数组拼成逗号分隔的字符串

• 多参数格式（multi）：适合后端期望ids=1&ids=2&ids=3这种形式

parameters:
  - name: ids
    in: query
    schema:
      type: array
      items:
        type: integer
    style: form
    explode: true # 关键：设为true会生成多个同名参数

Swagger 2.0 #

用collectionFormat指定格式：

• collectionFormat: csv：对应逗号分隔
• collectionFormat: multi：对应多参数

Swagger UI里的操作步骤 #

1. 打开你的Swagger UI页面，找到目标GET接口，点击「Try it out」
2. 根据你配置的格式输入参数：
   • 如果是逗号分隔格式：直接在参数输入框里填1,2,3（整数数组）或者apple,banana（字符串数组）
   • 如果是多参数格式：输入框旁边会出现「+」按钮，点击添加多个输入框，每个框填一个数组元素（比如第一个填1，第二个填2）
3. 点击「Execute」发送请求即可

你之前传参失败的常见原因 #

• 格式不匹配：后端期望多参数格式，但你配置成了逗号分隔，导致后端解析不到正确数组
• 类型错误：比如数组元素是整数，但你输入了带引号的字符串（比如填了"1","2"而不是1,2）
• 版本兼容问题：用了旧版本Swagger的collectionFormat但后端不支持对应的解析逻辑

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