openapi3-设置multipart/form-data
🔍 遇到问题
最近在写外包的时候，我引入了 knife4j，并且开启了 knife4j 的增强模式，但是发现在接口文档中，上传有些文件接口的请求参数类型是 x-www-form-urlencoded，或者是 application/json。
但是实际上我们传文件，一般建议请求参数类型是 multipart/form-data。当你尝试去修改 Controller 入参的注解的时候，你会发现你的请求参数类型总不是 multipart/form-data。
TIP
虽然你在某些注解下的条件可以在接口工具中选择 multipart/form-data 然后填数据（比如 @RequestParam），但是我希望在接口文档中能直接请求和看见想要的格式，这样测试和沟通也比较方便。
💡 解决方法
我简单举例几个。
单独上传文件的场景
@Parameter(
content = @Content(
mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
schemaProperties = {
@SchemaProperty(name = "fileField01", schema = @Schema(type = "string", format = "binary"))
}
)
)
public Result<RecoverImageUploadVO> RP_foreignpackage_image(List<MultipartFile> fileField01)
INFO
这是一个 Controller 类下的一个方法，用于上传文件。关于为什么是 List 的 MultipartFile，这个不用在意。
文件和其他参数一起传
@Parameter(
content = @Content(
mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
schemaProperties = {
@SchemaProperty(name = "files", schema = @Schema(type = "string", format = "binary")),
@SchemaProperty(name = "tBasicdata_company", schema = @Schema(implementation = TBasicdata_company.class))
}
)
)
public Result<CompanyResponseVO> createCompany(String tBasicdata_company, List<MultipartFile> files)
INFO
这同样是 Controller 类下的一个方法，这是多了一个参数，直接用 implementation 指定相应类的 class 就行，映射为类用 ObjectMapper 就行了。如果想在表单增加一个字符串参数，那么在方法参数中增加一个字符串参数即可，也用 @SchemaProperty 指定一下类型就行（文件也可以这样写 @SchemaProperty(name = "fileField02", schema = @Schema(implementation = MultipartFile.class)) 类似的）。
📝 总结
经过上面的了解，大家已经会在 swagger 文档中指定 multipart/form-data 了，后面打开文档的时候，找到相应的接口，就能直接上传文件了（别问为什么不用 swagger2）。
TIP
对于这类问题，我首先是问了 AI，但是 AI 不会这个，给我乱出主意。后面搜索了类似的话题，发现了帮助，后面又去研究了一下官方文档。当然，以上的示例肯定是无法满足所有场景的，我只是在外包项目中截取了两个代码块。
目标文档：点击这里跳转