Knife4j v4.0版本针对参数解析ParameterObject的问题说明
备注说明
该文档仅限Knife4j v4.0.0版本作为一种解决方案,在未来Knife4j v4.1.0版本中,会将springdoc-openapi的基础版本升级到最新版本,这样开发者就不用在maven中使用exclusions
进行排除低版本再重新引入了
先来看示例代码:
@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
在Knife4j 4.0.0版本中,排除低版本做升级即可,Maven配置如下:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>4.0.0</version>
<!--排查低版本-->
<exclusions>
<exclusion>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-common</artifactId>
</exclusion>
<exclusion>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-core</artifactId>
</exclusion>
<exclusion>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-models</artifactId>
<version>2.2.7</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.2.7</version>
</dependency>
<!--springdoc-openapi的Jar包引用-->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-common</artifactId>
<version>1.6.14</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-core</artifactId>
<version>1.6.14</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId>
<version>1.6.14</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>