跳到主要内容

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>