SpringBoot整合Swagger3时List类型参数无法输入多个值怎么办？

云原生阿岚

2026-9-25

Swagger3 List类型请求参数多值输入解决方案

问题根因

springfox 3.0.0 存在原生解析Bug，无法自动识别@RequestParam修饰的集合类型参数的数组属性，导致Swagger UI错误渲染为单值整数输入框。

修复步骤

给List类型参数添加Swagger3原生的@Parameter注解，手动指定数组类型schema，注意使用io.swagger.v3.oas.annotations.Parameter包下的注解，不要混用旧版Swagger2的@ApiParam注解（原有@ApiParam可以保留也可以替换为@Parameter的description属性）
修复后的代码示例：

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;

@DeleteMapping("/rate")
public void deleteRate(@ApiParam(value = "dc id") @RequestParam(required = false) Integer dcId,
                       @Parameter(description = "rate id", schema = @Schema(type = "array", implementation = Integer.class))
                       @RequestParam(required = false) List<Integer> dcrIdList) {
    // 原有业务逻辑
}

如果手动指定schema后，逗号分隔输入仍然报错，添加Spring MVC集合参数格式配置，支持csv格式的集合参数解析，在application.properties/application.yml中添加如下配置：
properties格式：
```
spring.mvc.format.collection=csv
```
yaml格式：
```
spring:
  mvc:
    format:
      collection: csv
```
清理项目编译缓存重启服务，重新打开Swagger UI页面，此时List参数会正确渲染为数组输入组件，支持多值输入，也兼容逗号分隔的单输入框传值方式。