Springdoc OpenAPI 2.0+配置文件上传框
Springdoc OpenAPI 2.0+中文件上传框的配置
问题
在Springdoc OpenAPI 2.0+中,用老的Spring标注会出现没有办法显示文件上传组件的问题。
2024年8月补充: 感谢"宇宙小神特别萌"的更正。符合Spring规范的方法会在下面总结
代码
/* EmployeeController.java **/
@RequestMapping("/api/v1/resume")
@RestController
public class OssController {
@Autowired
FileUploadService fileUploadService;
@PostMapping("/upload")
public void uploadResume(@RequestPart("file") MultipartFile file, @RequestParam String employee_id) {
// upload file
fileUploadService.uploadResume(file, employee_id);
}
}
其中@RequestPart("file")
在Swagger中用于标注文件上传组件,如果没有正常配置,会出现如图的文本框。
适用的操作
1. 最简单的方法是去除相关标注,让Spring自动识别(不推荐)
...
@PostMapping("/upload")
public void uploadResume(MultipartFile file, @RequestParam("employee_id") String employee_id){
// upload file
fileUploadService.uploadResume(file, employee_id);
}
...
但并不是最佳实践
2. 控制器层面配置(推荐)
在你的控制器方法中,通过 @PostMapping
的 consumes
属性定义 Content-Type
为 multipart/form-data
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadFile(@RequestPart("file") MultipartFile file, @RequestParam("employee_id") String employee_id) {
// Handle file upload
fileUploadService.uploadResume(file, employee_id);
}
3. Swagger 配置层面定义(Swagger3新版本の方法)
在使用 Swagger 3.0(OpenAPI 3.0)时,如果要在 API 文档中显示文件上传的支持,你可以通过 @Operation
或 @RequestBody
注解来明确指定 multipart/form-data
其中@Operation
用于定义和描述这个 API 端点的具体行为
@ApiResponses
用于定义这个端点的可能响应以及对应的描述信息
@Operation(summary = "Upload a file", description = "Upload a file using multipart/form-data")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "File uploaded successfully")
})
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadFile(
@Parameter(description = "File to upload", required = true)
@RequestPart("file") MultipartFile file) {
// Handle file upload
fileUploadService.uploadResume(file, employee_id);
}
4. 全局配置文件(如 application.yml 或 application.properties)
如果是application.yml
:
spring:
mvc:
content-type: multipart/form-data
如果是application.properties
:
spring.mvc.content-type=multipart/form-data
上述方法都能取得正确的文件输入框