Spring Boot结合Swagger处理Multipart表单请求的渲染异常问题

你遇到的这个情况很典型：Spring本身可以通过StandardServletMultipartResolver完美处理Multipart表单请求到@RequestBody对象的绑定，但Springfox 2.8.0默认没适配这种特殊用法，导致Swagger UI里的请求体渲染不符合预期（比如显示成JSON结构而非表单输入框）。下面给你几个可行的解决方案：

方案1：用@ApiImplicitParams手动声明表单字段 #

如果你不想改动现有控制器的注解逻辑，可以直接给接口方法添加@ApiImplicitParams，手动指定每个表单字段的信息，让Swagger渲染出正确的表单输入项：

@PostMapping(value = "/foo", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@ApiImplicitParams({
    @ApiImplicitParam(name = "field1", dataType = "string", paramType = "form", required = true),
    @ApiImplicitParam(name = "field2", dataType = "int", paramType = "form"),
    // 这里对应Foo类中的所有字段，按需添加
})
public void postFooAsMultiPart(@RequestBody Foo foo) {
    // 你的业务逻辑
}

这种方式的好处是不需要修改现有绑定逻辑，直接给Swagger补充元数据即可。

方案2：改用@RequestPart配合ApiModel注解 #

这是更符合Swagger规范的做法，同时Spring依然能正常处理Multipart请求绑定。

首先给你的Foo类添加Swagger模型注解：

@ApiModel(description = "Foo请求对象")
public class Foo {
    @ApiModelProperty(value = "第一个字段", required = true)
    private String field1;
    
    @ApiModelProperty(value = "第二个字段")
    private Integer field2;
    
    // 省略getter/setter
}

然后修改控制器方法的参数注解为@RequestPart：

@PostMapping(value = "/foo", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public void postFooAsMultiPart(@RequestPart Foo foo) {
    // 你的业务逻辑
}

这样Springfox会自动识别Foo类的字段，在Swagger UI中渲染出对应的表单输入框，同时保持Spring对请求的正常绑定处理。

方案3：自定义Springfox插件（进阶） #

如果既不想改控制器注解，也不想手动声明每个字段，可以自定义一个Springfox的插件，让它自动识别@RequestBody配合MULTIPART_FORM_DATA的场景，将请求体类型转换为表单格式。示例代码大致如下：

@Component
public class MultipartRequestBodyPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        // 判断当前接口是否是Multipart请求且使用了@RequestBody
        boolean isMultipart = context.consumes().contains(MediaType.MULTIPART_FORM_DATA_VALUE);
        Optional<RequestBody> requestBody = context.findAnnotation(RequestBody.class);
        if (isMultipart && requestBody.isPresent()) {
            // 获取参数类型
            ResolvedType paramType = context.getParameters().stream()
                    .filter(p -> p.hasParameterAnnotation(RequestBody.class))
                    .findFirst()
                    .map(ParameterContext::getParameterType)
                    .orElse(null);
            if (paramType != null) {
                // 生成表单类型的请求体
                ModelReference modelRef = ModelConverters.getInstance()
                        .readAsModel(paramType.getErasedType())
                        .getModelReference();
                context.operationBuilder()
                        .requestBody(RequestBodyBuilder.requestBody()
                                .content(ContentBuilder.content()
                                        .mediaType(MediaType.MULTIPART_FORM_DATA_VALUE)
                                        .schema(new Schema(modelRef))
                                        .build())
                                .build());
            }
        }
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return SwaggerPluginSupport.pluginDoesApply(delimiter);
    }
}

这个插件会自动处理符合条件的接口，让Swagger正确渲染表单字段，但需要注意Springfox 2.8.0的API细节，可能需要根据实际情况调整。

另外，如果项目依赖允许的话，升级Springfox到3.x及以上版本会更省心——新版本对Multipart请求与对象绑定的场景支持更完善，大概率不需要额外配置就能正常渲染。

内容的提问来源于stack exchange，提问作者Andy N