OpenApi 3.0中REST接口Map<String,List<String>>参数映射问题

问题根源 #

OpenAPI 3.0 对 @RequestPart 参数的处理逻辑和 Swagger v2 完全不同：

• Swagger v2 会将 @RequestPart 泛型参数自动识别为 body 参数，但 OpenAPI 3.0 中 @RequestPart 属于 multipart 请求的独立部件，不再归为 body 参数范畴。
• 你之前添加的 @Schema 配置没有正确描述泛型嵌套结构（Map<String, List<String>>），且 @Parameter 注解和 @RequestPart 混用会干扰 OpenAPI 3.0 的参数解析逻辑，导致参数被忽略。

解决步骤 #

1. 移除冗余注解 #

删掉 @Parameter 注解，@RequestPart 本身已经支持 description 属性，无需额外标注。

2. 正确配置 @Schema 描述泛型结构 #

针对 Map<String, List<String>> 的嵌套类型，需要通过 @Schema 的 additionalProperties 明确指定值的类型为字符串数组：

@RestController
public class YourController {

    @PostMapping(value = "/pathto/mymethod", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<?> yourMethod(
            // 正确的参数注解配置
            @RequestPart(required = false, description = "My example")
            @Schema(
                type = "object",
                additionalProperties = @Schema(
                    type = "array",
                    items = @Schema(type = "string")
                ),
                example = "{ \"key\": [\"value1\", \"value2\"] }"
            )
            Map<String, List<String>> someData
    ) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }
}

3. 确保请求的媒体类型正确 #

在方法上通过 consumes = MediaType.MULTIPART_FORM_DATA_VALUE 明确指定接口接收 multipart 类型请求，OpenAPI 3.0 只会解析该类型下的 @RequestPart 参数。

4. 检查依赖版本（若使用 SpringDoc） #

如果你的项目用的是 SpringDoc OpenAPI（替代停更的 SpringFox），确保使用的是 v1.6.0+ 版本，旧版本存在泛型参数解析的 bug，会导致嵌套泛型类型无法被正确识别。

验证效果 #

配置完成后，重新生成 api-docs，someData 参数会出现在 multipart 请求的 requestBody -> content -> multipart/form-data -> schema -> properties 中，完整展示其类型结构和示例。

内容的提问来源于stack exchange，提问作者Sorin-Alexandru Cristescu