Spring Boot嵌套DTO中MultipartFile在Swagger无上传按钮问题求助

问题场景 #

在Spring Boot项目中，文件上传字段存在于嵌套DTO结构中：WarrantyRequestNormalCreationDto包含WarrantyRequestNormalPartsCreationDto列表，每个列表项都带有MultipartFile类型的文件字段。但在Swagger界面测试时，这些文件字段未显示文件上传选择按钮，只能手动输入文件路径。

解决步骤 #

1. 显式标记文件字段的Swagger类型 #

Swagger默认无法自动识别嵌套对象/列表中的MultipartFile为文件上传控件，需要通过注解显式指定字段类型：

• 给所有MultipartFile字段添加@Schema(type = "string", format = "binary")，告诉Swagger这是二进制文件类型
• 配合@Parameter注解指定媒体类型为multipart/form-data

修改后的子DTO代码：

public class WarrantyRequestNormalPartsCreationDto implements Serializable {
    // 其他字段...

    @NotBlank
    private String numberplateFileName;
    
    @EqualsAndHashCode.Exclude
    @Parameter(content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE))
    @Schema(type = "string", format = "binary")
    private MultipartFile numberplateFile;
    
    // 其他字段...
}

父DTO中的文件字段也做同样修改：

public class WarrantyRequestNormalCreationDto extends WarrantyRequestNormalDetailsDto {
    private String reparationPictureFileName;
    
    @EqualsAndHashCode.Exclude
    @Parameter(content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE))
    @Schema(type = "string", format = "binary")
    private MultipartFile reparationPictureFile;
    
    private String workOrderFileName;
    
    @EqualsAndHashCode.Exclude
    @Parameter(content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE))
    @Schema(type = "string", format = "binary")
    private MultipartFile workOrderFile;
    
    private List<@Valid WarrantyRequestNormalPartsCreationDto> warrantyRequestNormalParts;
}

2. 控制器方法正确接收请求 #

文件上传请求使用multipart/form-data格式，不能用@RequestBody接收，需要改用@ModelAttribute：

@PostMapping(value = "/warranty", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<Void> createWarranty(
        @ModelAttribute @Valid WarrantyRequestNormalCreationDto dto) {
    // 处理文件上传和业务逻辑
    return ResponseEntity.ok().build();
}

3. 确保Swagger配置支持Multipart #

如果使用SpringDoc（推荐的Swagger3实现），确保依赖正确引入，默认已支持multipart请求。若使用SpringFox（旧版Swagger2），需在Docket配置中启用相关支持：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.path"))
            .paths(PathSelectors.any())
            .build()
            .enableUrlTemplating(false);
}

原理说明 #

Swagger对嵌套在复杂结构（如列表、嵌套DTO）中的MultipartFile类型缺乏自动识别能力，需要通过@Schema和@Parameter注解明确告知Swagger该字段的二进制文件属性；同时控制器必须使用@ModelAttribute来解析multipart/form-data格式的请求，才能让Swagger正确渲染文件上传控件。

内容的提问来源于stack exchange，提问作者Eya Cherni