Spring Boot项目Swagger V3中@RequestBody搭配MultiValueMap失效问题

AI 小北

2026-9-24

问题修复方案

第一步：修正MultiValueMap的泛型声明
必须显式指定键值泛型，否则Swagger3的参数解析器无法识别请求体结构，写法参考：
```
@PostMapping("/your/api")
public void test(@RequestBody MultiValueMap<String, String> params) {
  // 业务逻辑
}
```

第二步：清理依赖冲突
移除所有旧版Swagger2（io.springfox组）的依赖，统一使用OpenAPI v3官方starter，普通Spring Web项目依赖参考：

<!-- Maven 依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>最新稳定版</version>
</dependency>

第三步：显式指定请求体媒体类型
如果泛型配置正确仍然拿不到值，可通过OpenAPI注解显式指定请求体类型，避免Swagger自动识别错误：
```
@PostMapping("/your/api")
public void test(
    @org.springframework.web.bind.annotation.RequestBody
    @io.swagger.v3.oas.annotations.parameters.RequestBody(
        content = @Content(mediaType = "application/json")
    )
    MultiValueMap<String, String> params
) {
  // 业务逻辑
}
```
注意：如果是表单提交场景，无需添加@RequestBody注解，直接声明MultiValueMap<String, String> params即可，加注解会触发JSON解析器解析表单数据，导致参数为空。
第四步：验证配置生效
重启项目后打开Swagger UI，进入对应接口详情页，查看请求体Schema是否正确显示为键值对结构，再调试传参确认参数可正常接收。