【随笔】【Java Spring Springdoc OpenAPI/Swagger 3.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. 控制器层面配置(推荐)

在你的控制器方法中,通过 @PostMappingconsumes 属性定义 Content-Typemultipart/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

上述方法都能取得正确的文件输入框
正确的

评论 3
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值