Spring Boot3迁移后SpringDoc SwaggerUI无法解析DTO内多值请求参数

1. 全局配置属性（最优解） #

直接在项目配置文件中添加以下配置，让springdoc自动将所有用作GET请求参数的POJO视为@ParameterObject：

application.yml #

springdoc:
  default-flat-param-object: true

application.properties #

springdoc.default-flat-param-object=true

这个配置会自动扁平化所有请求参数对象，DTO中的List<String>/List<Integer>字段会被Swagger UI正确识别为多值参数，调用时会生成?values=test&values=test1的格式，而非编码后的字符串数组。

2. 自定义全局插件（备选方案） #

如果上述配置不生效，可以自定义一个OperationCustomizer，针对所有GET接口自动处理DTO参数：

import io.swagger.v3.oas.models.Operation;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.method.HandlerMethod;

import java.lang.reflect.Parameter;
import java.util.Map;

@Component
public class GlobalGetParamObjectCustomizer implements OperationCustomizer {

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        // 仅处理GET请求的接口
        if (handlerMethod.hasMethodAnnotation(GetMapping.class)) {
            Parameter[] methodParams = handlerMethod.getMethodParameters();
            for (int i = 0; i < methodParams.length; i++) {
                Parameter param = methodParams[i];
                Class<?> paramType = param.getType();
                // 过滤掉基本类型、JDK内置类型，只处理自定义DTO
                if (!paramType.isPrimitive() && !paramType.getName().startsWith("java.")) {
                    if (i < operation.getParameters().size()) {
                        // 标记参数为ParameterObject，触发多值参数解析
                        operation.getParameters().get(i).setExtensions(
                            Map.of("x-parameter-object", Boolean.TRUE)
                        );
                    }
                }
            }
        }
        return operation;
    }
}

问题根源 #

Spring Boot 3.x配套的springdoc-openapi-starter-webmvc-ui调整了默认行为：旧版springdoc-openapi-ui会自动将GET请求的DTO参数扁平化，而新版starter需要显式通过配置或注解开启该行为，导致未添加@ParameterObject的DTO中的集合字段被识别为字符串对象。

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