Springfox-oas无法生成数组类型查询参数问题排查

方案1：用@Parameter注解显式声明数组类型 #

在@RequestParam上方添加Swagger OAS3的@Parameter注解，明确指定参数为数组类型：

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

@ApiOperation(value = "Get the value drivers for a part by its as JSON output")
@GetMapping(AppConstants.VDJSON)
ValueDriver getValueDriverJson(
        @Parameter(in = ParameterIn.QUERY, 
                   schema = @Schema(type = "array", 
                                   arraySchema = @Schema(type = "string")))
        @RequestParam(value="pnrList")
        final ArrayList<String> pnrList);

方案2：改用List<String>替代ArrayList<String> #

Springfox对List接口的类型推断支持更完善，直接将参数类型改为List<String>，无需额外注解就能正确识别为数组：

@ApiOperation(value = "Get the value drivers for a part by its as JSON output")
@GetMapping(AppConstants.VDJSON)
ValueDriver getValueDriverJson(
        @RequestParam(value="pnrList")
        final List<String> pnrList);

方案3：全局配置参数类型解析（批量场景适用） #

如果有大量同类参数需要处理，可以创建Springfox配置类，自定义OAS3转换规则：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.oas.web.OpenApiTransformationContext;
import springfox.documentation.oas.web.WebMvcOpenApiTransformationFilter;
import springfox.documentation.spi.DocumentationType;
import io.swagger.v3.oas.models.OpenApi;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.media.Schema;
import jakarta.servlet.http.HttpServletRequest;

import java.util.List;

@Configuration
public class SpringfoxOasConfig {
    @Bean
    public WebMvcOpenApiTransformationFilter arrayQueryParamFixFilter() {
        return new WebMvcOpenApiTransformationFilter() {
            @Override
            public OpenApi transform(OpenApiTransformationContext<HttpServletRequest> context) {
                OpenApi openApi = context.getSpecification();
                // 遍历所有路径和操作，修正查询参数中的集合类型定义
                openApi.getPaths().values().forEach(pathItem -> {
                    pathItem.readOperations().forEach(operation -> {
                        operation.getParameters().forEach(param -> {
                            if ("query".equals(param.getIn()) && param.getSchema() != null) {
                                // 实际场景中可通过Spring的RequestMappingHandlerMapping获取方法参数信息
                                if (List.class.isAssignableFrom(getParamActualType(param, operation))) {
                                    param.getSchema().setType("array");
                                    param.getSchema().setItems(new Schema().type("string"));
                                }
                            }
                        });
                    });
                });
                return openApi;
            }

            private Class<?> getParamActualType(io.swagger.v3.oas.models.parameters.Parameter param, Operation operation) {
                // 示例简化处理，实际需根据项目逻辑获取真实参数类型
                return List.class;
            }

            @Override
            public boolean supports(DocumentationType documentationType) {
                return DocumentationType.OAS_30.equals(documentationType);
            }
        };
    }
}

注意事项 #

• 方案2是最简便的解决方式，优先推荐，Springfox对List接口的类型映射逻辑更完善。
• 方案1适合需要给单个参数添加额外描述、示例值等精细化配置的场景。
• 方案3适合全局统一处理多个集合类型查询参数的场景，实现相对复杂，需根据实际项目调整类型解析逻辑。

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