SpringBoot项目Swagger UI 3.0文件上传参数未在界面展示问题

如果你使用的是Swagger 2.x（SpringFox 2.x版本） #

正确配置有两种方式，优先选第一种更不容易出错：

• 方式一：直接在接口参数上声明注解，不需要写@ApiImplicitParam

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@ApiOperation(value = "文件上传接口")
public R upload(
    @ApiParam(value = "上传的文件", required = true) 
    @RequestParam("mediafile") 
    MultipartFile mediafile
) {
    // 业务逻辑
}

• 方式二：如果你一定要用@ApiImplicitParam配置，注意参数值要符合Swagger2的规则
  你原来的代码错误点是dataTypeClass配置不对，Swagger2识别文件类型需要用固定值__file，正确配置如下：

@ApiImplicitParam(
    name = "mediafile", 
    value = "upload the file", 
    dataType = "__file", 
    required = true, 
    paramType = "formData"
)
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public R upload(MultipartFile mediafile) {
    // 业务逻辑
}

如果你使用的是OpenAPI 3.x（SpringDoc或者SpringFox 3.x版本） #

旧版@ApiImplicitParam已经不适用，直接在参数上配置如下注解即可：

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@Operation(summary = "文件上传接口")
public R upload(
    @Parameter(
        description = "上传的文件", 
        content = @Content(
            mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
            schema = @Schema(type = "string", format = "binary")
        )
    )
    @RequestPart("mediafile") 
    MultipartFile mediafile
) {
    // 业务逻辑
}

通用排查点 #

• 不要在文件上传接口上加@RequestBody注解，该注解会强制接口使用JSON格式传参，覆盖formData配置
• 检查自定义的Swagger配置类，没有过滤MultipartFile类型的参数
• 确认接口的请求方式为POST，且配置了consumes = MediaType.MULTIPART_FORM_DATA_VALUE

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