Knife4j版本参考
以下是关于Knife4j适配不同Spring Boot版本的说明文档
本文档旨在帮助开发者选择适合其项目的Knife4j版本与Spring Boot版本的适配。请根据您的项目要求和使用的Spring Boot版本选择适当的Knife4j版本。
1.前世今生
在更名为Knife4j
之前,原来的名称是叫swagger-bootstrap-ui
,这是两种不一样风格的Ui,对比情况如下:
名称 | 开发语言&框架 | 状态 | 最后版本 | 风格 |
---|---|---|---|---|
Knife4j | Java、JavaScript、Vue | 持续更新中... | 无 | 黑色 |
swagger-bootstrap-ui | Java、JavaScript、jQuery | 停更 | 1.9.6 | 蓝色 |
Knife4j从开源至今,目前主要经历版本的变化,分别如下:
版本 | 说明 |
---|---|
1.0~1.9.6 | 名称是叫swagger-bootstrap-ui ,蓝色风格Ui |
1.9.6 | 蓝色皮肤风格,开始更名,增加更多后端模块 |
2.0~2.0.5 | Ui基于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.2 | Knife4j 2.0.0 ~ 2.0.6 | >=Knife4j 4.0.0 |
2.2.x~2.4.0 | Knife4j 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规范的说明:
Knife4j版本 | Swagger2规范 | OpenAPI3规范 | 说明 |
---|---|---|---|
1.0~1.9.6 | springfox 2.9.2 | 无 | Knife4j的前身,名称为swagger-bootstrap-ui |
1.9.6~2.0.5 | springfox 2.9.2 | 无 | |
2.0.6~2.0.9 | springfox 2.10.5 | 无 | |
3.0.0~3.0.3 | springfox 3.0.3 | 无 | 过度版本,建议开发者不要使用 |
4.0.0~ | springfox 2.10.5 | >=springdoc-openapi 1.6.9 | Swagger2规范稳定使用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的版本过程中仍然存在疑惑,可以通过关注文档底部的微信公众号,点击菜单加入微信交流群,与作者当面对话。