项目版本 SpringBoot 3.3.2
项目依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
1. Knife4j v4.0版本针对参数解析 ParameterObject 的问题说明
先来看示例代码：
@Operation(summary = "Get 请求", tags = "对接口分组", description = "对接口的作用进行描述")
@RequestMapping(value = "/api/v1/open-api", method = RequestMethod.GET)
public R<GetDTO> get(GetDTO dto) {
return R.ok(dto);
}
实体类GetDTO.java
@Data
@Schema(description = "请求 Param 对象")
class GetDTO {
@Schema(description = "param 必填参数", required = true, example = "param 必填参数")
private String paramRequired;
@Schema(description = "param 非必填参数", example = "param 非必填参数")
private String paramNoRequired;
}
这种情况在之前springfox的框架下，会直接解析成 form 参数，开发者无需过多的配置，但是在升级到 Knife4j v4.0版本后，文档的界面效果却和开发者展示的不一样，如下图：
很多朋友会误以为这是Knife4j的前端Ui解析Bug，但其实不是，针对这种情况，目前有两种解决方案：
1. 加注解
所有的该类型的接口中，增加注解@ParameterObject,代码最终如下：
@Operation(summary = "Get 请求", tags = "对接口分组", description = "对接口的作用进行描述")
@RequestMapping(value = "/api/v1/open-api", method = RequestMethod.GET)
public R<GetDTO> get(@ParameterObject GetDTO dto) {
return R.ok(dto);
}
但是这种情况很多开发者可能会觉得很麻烦，因为如果涉及到接口太多的话，那么确实每个接口都需要加注解的话，工作量会非常的大
提示
但是这种情况很多开发者可能会觉得很麻烦，因为如果涉及到接口太多的话，那么确实每个接口都需要加注解的话，工作量会非常的大
2. 改配置
第二种情况则是在目前 Knife4j 的 v4.0.0 版本中，可以考虑升级 springdoc-openapi 的版本来解决，通过新特性，一行配置搞定
在 springdoc-openapi 的 1.6.11 版本中，增加了defaultFlatParamObject的配置项，通过配置该属性，可以不用添加注解，达到上面 1. 中的效果
在项目yml配置中，配置如下：
springdoc:
# 默认是false，需要设置为true
default-flat-param-object: true
文章参考：www.yuque.com/u27430045/x…
2. OpenAPI 代码生成没有 MultipartFile 参数问题
1. Java 代码：
@PostMapping(value = "/upload")
public BaseResponse<String> uploadFile(@RequestPart("file") MultipartFile multipartFile,
UploadFileRequest uploadFileRequest) {
}
此时 swagger 生成的接口文档格式为 json
生成代码无 file，无法作为参数传给后端
2. 解决方法
应把 json 格式改为：multipart/form-data
在注解后加参数：consumes = {"multipart/form-data"}
@PostMapping(value = "/upload", consumes = {"multipart/form-data"})
public BaseResponse<String> uploadFile(@RequestPart("file") MultipartFile multipartFile,
UploadFileRequest uploadFileRequest) {
}
此时生成的代码为有 file
代码可以正常调用
