如何在Swagger UI中将API参数定义为formData类型

Springfox 2.8.0版本对@RequestParam标注的Map<String, String>类型参数存在固定解析逻辑，默认将其识别为query类型传参，不会自动归入multipart/form-data的表单参数范畴，即使接口已经定义了MultipartFile类型的表单参数。

方法1：注解显式声明参数类型（无侵入、最推荐） #

不需要修改现有业务逻辑，仅通过Swagger注解显式指定参数位置即可：

1. 给@PostMapping注解补充consumes属性，显式声明接口接收multipart/form-data类型的请求：

   @PostMapping(produces = "application/json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
   

2. 在方法上添加@ApiImplicitParams注解，显式指定metadata参数的传参位置为表单：
   调整后的完整接口代码如下：

   @RestController
   @RequestMapping("/v1/files")
   public class FileController {
   
       @ApiOperation("文件上传接口")
       @ApiImplicitParams({
           @ApiImplicitParam(name = "metadata", value = "文件元数据", paramType = "form", dataType = "java.util.Map")
       })
       @PostMapping(produces = "application/json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
       public ResponseEntity<UploadFileResponse> uploadFile(
               @ApiParam(value = "Metadata of file") @RequestParam Map<String, String> metadata,
               @ApiParam(value = "File to upload", required = true) @RequestParam MultipartFile file)
               throws IOException {
           // 业务逻辑
       }
   }
   

   注意：@ApiImplicitParam的name属性值必须和方法形参名完全一致（即metadata），否则配置不生效。
   重启服务后刷新Swagger UI，即可看到metadata参数被识别为formData类型。

方法2：封装参数实体（固定元数据字段场景推荐） #

如果metadata的字段是固定的，可以直接将Map参数替换为普通实体类接收，Springfox会自动将实体类字段识别为表单参数，不需要额外配置隐式参数：

1. 定义元数据实体类：

   @Data
   public class FileMetadata {
       @ApiModelProperty(value = "文件名")
       private String fileName;
       @ApiModelProperty(value = "文件存储路径")
       private String path;
       // 按需补充其他固定元数据字段
   }
   

2. 修改接口形参：

   @PostMapping(produces = "application/json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
   public ResponseEntity<UploadFileResponse> uploadFile(
           FileMetadata metadata,
           @ApiParam(value = "File to upload", required = true) @RequestParam MultipartFile file)
           throws IOException {
       // 业务逻辑
   }
   

方法3：升级Springfox版本（解决原生解析bug） #

2.8.0版本本身对multipart请求中的Map类型参数解析存在已知bug，若以上配置不生效，可以直接升级Springfox到2.9.2稳定版，升级后仅需要给接口添加consumes = MediaType.MULTIPART_FORM_DATA_VALUE声明，即可自动识别Map类型的表单参数。
修改build.gradle中的依赖：

implementation('io.springfox:springfox-swagger2:2.9.2')
implementation('io.springfox:springfox-swagger-ui:2.9.2')

接口显示截图

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