Spring Boot 集成 Swagger 时，若文件上传接口未显示上传控件，通常因 @RequestMapping 中误用 produces 而非 consumes；只需将 produces = "multipart/form-data" 改为 consumes = "multipart/form-data"，Swagger 即可识别并渲染文件选择器。
spring boot 集成 swagger 时，若文件上传接口未显示上传控件，通常因 `@requestmapping` 中误用 `produces` 而非 `consumes`；只需将 `produces = "multipart/form-data"` 改为 `consumes = "multipart/form-data"`，swagger 即可识别并渲染文件选择器。
在 Spring MVC 中，consumes 属性用于声明该接口接收（消费）的请求媒体类型（如 multipart/form-data），而 produces 表示接口返回（生成）的响应媒体类型（如 application/json）。文件上传本质是客户端向服务端发送 multipart/form-data 格式的请求体，因此必须通过 consumes 显式声明，否则 Swagger（基于 OpenAPI 规范）无法推断出需渲染 <input type="file"> 控件。
✅ 正确写法如下：
@PostMapping(value = "/add")
@ResponseStatus(HttpStatus.OK)
public void addFile(
@RequestParam("file") MultipartFile file
) throws Exception {
fileservice.addAttachment(file); // 注意：方法名建议遵循 Java 驼峰命名规范（addAttachment）
}
或显式指定 consumes（推荐，语义更清晰）：
@PostMapping(
value = "/add",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE // 等价于 "multipart/form-data"
)
public void addFile(@RequestParam("file") MultipartFile file) throws Exception {
fileservice.addAttachment(file);
}
⚠️ 注意事项：
- 不要使用
produces = "multipart/form-data"——该值通常用于文件下载接口（如ResponseEntity<resource></resource>返回二进制流），与上传无关； - 确保项目已引入
springdoc-openapi-ui（新版 Swagger UI 推荐）或springfox-swagger2（旧版），且控制器类被 Swagger 扫描到； - 若使用 Spring Boot 3.x + Springdoc 2.x，需确认
@OpenAPIDefinition或@Operation注解未意外覆盖默认行为； - 建议配合
@Schema(description = "上传的文件", required = true)对@RequestParam增强文档描述，提升 API 可读性。
总结：Swagger 文件上传控件的显示依赖 OpenAPI 对请求体类型的准确识别，核心在于正确使用 consumes 属性。修正后，访问 /swagger-ui.html（Springfox）或 /swagger-ui/index.html（Springdoc）即可看到带“Choose File”按钮的交互式表单，大幅提升前后端联调效率。
