跳到主要内容

Knife4j版本参考

以下是关于Knife4j适配不同Spring Boot版本的说明文档

版本规范说明

本文档旨在帮助开发者选择适合其项目的Knife4j版本与Spring Boot版本的适配。请根据您的项目要求和使用的Spring Boot版本选择适当的Knife4j版本。

1.前世今生

在更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui,这是两种不一样风格的Ui,对比情况如下:

名称开发语言&框架状态最后版本风格
Knife4jJava、JavaScript、Vue持续更新中...黑色
swagger-bootstrap-uiJava、JavaScript、jQuery停更1.9.6蓝色

Knife4j从开源至今,目前主要经历版本的变化,分别如下:

版本说明
1.0~1.9.6名称是叫swagger-bootstrap-ui,蓝色风格Ui
1.9.6蓝色皮肤风格,开始更名,增加更多后端模块
2.0~2.0.5Ui基于Vue2.0+AntdV重写,黑色风格,参考示例,底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9底层springfox框架版本升级至2.10.5,,仅提供Swagger2规范的适配
3.0~3.0.3底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本,建议开发者不要使用
4.0~区分OpenAPI2和Swagger3的Maven坐标artifactId
OpenAPI2规范服务端解析框架稳定在springfox2.10.5
OpenAPI3框架服务端解析跟随springdoc项目更新迭代
建议开发者使用该版本,请参考4.x升级文档

2.Spring Boot版本兼容性

首先,确保您了解您的项目所使用的Spring Boot版本。

以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐:

Spring Boot版本Knife4j Swagger2规范Knife4j OpenAPI3规范
1.5.x~2.0.0<Knife4j 2.0.0>=Knife4j 4.0.0
2.0~2.2Knife4j 2.0.0 ~ 2.0.6>=Knife4j 4.0.0
2.2.x~2.4.0Knife4j 2.0.6 ~ 2.0.9>=Knife4j 4.0.0
2.4.0~2.7.x>=Knife4j 4.0.0>=Knife4j 4.0.0
>= 3.0>=Knife4j 4.0.0>=Knife4j 4.0.0

Knife4j在之前的版本更新中,逐渐提供了一些服务端适配的增强特性功能。

但是开发者应该明白,不管是Swagger2规范还是OpenAPI3规范,Knife4j的最新版本的纯Ui版本,是可以适配Spring Boot所有版本的。

如果你不考虑使用Knife4j提供的服务端增强功能,引入Knife4j的纯Ui版本没有任何限制。只需要考虑不同的规范即可

2.1 Spring Boot 2.x

在Knife4j的4.0版本之前,开发者引用的方式是通过knife4j-spring-boot-starter进行使用,但是在4.0版本之后,开发者在引用时需要对选择不同的规范版本进行区分

Knife4j在组件中针对不同的规范版本做了区分,maven组件的artifactId已经发生了变化。

2.1.1 Swagger2规范

在4.0版本之前,应用坐标:

引用组件maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>{<4.0.0版本}</version>
</dependency>

自4.0版本开始,maven组件的artifactId已经发生了变化。

引用组件maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>{maven仓库最新版本}</version>
</dependency>

2.1.2 OpenAPI3规范

自4.0版本开始,Knife4j提供对OpenAPI3规范的适配,底层规范解析框架依赖springdoc-openapi项目

引用组件maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>{maven仓库最新版本}</version>
</dependency>

2.2 Spring Boot 3.x

由于springfox长久未更新,并且Swagger2规范在目前来看,一定程度上也并未升级,规范已经全部往OpenAPI3规范靠拢,因此,在Spring Boot 3.x版本中,开发者应该选择OpenAPI3规范来作为应用框架的开发首选方案。

Knife4j自4.0版本为Spring Boot 3框架提供了适配

引用组件maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>{maven仓库最新版本}</version>
</dependency>

3.规范说明

针对Swagger2规范OpenAPI3规范的说明:

服务端规范解析说明

在Spring Boot框架中,Knife4j对于服务端将Spring的开放接口解析成Swagger2或者OpenAPI3规范的框架,也是依赖的第三方框架组件。说明如下:

  • Swagger2规范:依赖Springfox项目,该项目目前几乎处于停更状态,但很多老项目依然使用的是该规范,所以Knife4j在更新前端Ui的同时也继续保持了兼容
  • OpenAPI3规范:依赖Springdoc项目,更新发版频率非常快,建议开发者尽快迁移过来使用OpenAPI3规范,Knife4j后面的重心也会在这里。
Knife4j版本Swagger2规范OpenAPI3规范说明
1.0~1.9.6springfox 2.9.2Knife4j的前身,名称为swagger-bootstrap-ui
1.9.6~2.0.5springfox 2.9.2
2.0.6~2.0.9springfox 2.10.5
3.0.0~3.0.3springfox 3.0.3过度版本,建议开发者不要使用
4.0.0~springfox 2.10.5>=springdoc-openapi 1.6.9Swagger2规范稳定使用springfox2.10.5保持不变。开发者应该尽早迁移到OpenAPI3规范上来,请参考4.x升级文档

4.网关聚合

自4.0版本后,Knife4j提供了一个针对在Spring Cloud Gateway网关进行聚合的组件knife4j-gateway,开发者可以基于此组件轻松的聚合各个子服务的OpenAPI文档

Maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>{大于4.0.0版本}</version>
</dependency>

由于开发网关聚合组件时,Knife4j所引用的Spring Cloud Gateway的依赖全部为Optional类型,常规操作下,开发者应该是在Gateway的任意版本中都能使用,但还是给出最低的推荐版本配置:

Spring Boot版本Knife4j Gateway网关聚合版本
>=2.4.8~3.x>=4.0.0

5.最后

如果您在选择使用Knife4j的版本过程中仍然存在疑惑,可以通过关注文档底部的微信公众号,点击菜单加入微信交流群,与作者当面对话。