跳到主要内容

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.2无Knife4j的前身，名称为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的版本过程中仍然存在疑惑，可以通过关注文档底部的微信公众号，点击菜单加入微信交流群，与作者当面对话。

最后由 xiaoyumin 于 更新