Knife4j 4.0正式发布

Knife4j 4.0版本正式发布了！

该版本处理了近12个月以来Gitee、GitHub两大平台积压的近300多个issue

同时也带来了一些新的特性。

主要更新亮点：

• 统一各个组件版本号,使用Knife4j时开发者根据需要自行引用,artifactId发生了变化
• 支持Spring Boot 3
• 兼容适配springdoc-openapi底层框架，全面迁移到OpenAPI3的规范支持
• 针对OpenAPI2(Swagger)规范提供了优化，开发者基于Spring Boot2版本可以无缝衔接
• Knife4j-Desktop组件架构升级重写，新架构支持不同需求的OpenAPI规范进行聚合
• 提供官方Docker镜像服务，基于Knife4j可方便在云服务上进行使用
• 官网文档更新重写

架构整理

为了以后Knife4j发展的可持续性，整个架构重新梳理，后续可以根据不同的需求，提供不同的服务

新的架构图，有的是规划(尚未实现)，有的已经实现，欢迎大佬一起贡献。

统一版本

在此次4.0版本中，统一各个版本，将OpenAPI2规范与OpenAPI3规范区分开，避免版本及规范混乱使用产生的误解，使用者可以更清晰

需要注意，4.0版本artifactId发生了变化

目前knife4j的项目结构：

模块名称	说明
knife4j-aggregation-spring-boot-starter	基于 Servlet 体系下的聚合中间件
knife4j-core	核心类,包含一些工具包、增强注解等
knife4j-dependencies	Knife4j 提供的 dependencies 工程，引入该工程后，knife4jspringfoxswaggerspringdoc-openapi 等版本号不用在独自声明
knife4j-openapi2-ui	增强 UI 文档,该包是一个 webjar,只包含前端代码，支持 OpenAPI2
knife4j-openapi3-ui	增强 UI 文档,该包是一个 webjar,只包含前端代码，支持 OpenAPI3
knife4j-gateway-spring-boot-starter	基于Spring Cloud Gateway网关的项目可以引用该组件实现简单的文档聚合,参考https://gitee.com/xiaoym/knife4j/tree/dev/knife4j/knife4j-gateway-spring-boot-starter
knife4j-openapi2-spring-boot-starter	基于 OpenAPI2 规范，在 Spring Boot < 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层依赖 springfox-swagger 2.10.5 项目
knife4j-openapi3-spring-boot-starter	基于 OpenAPI3 规范，在 Spring Boot < 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层基于 springdoc-openapi 项目
knife4j-openapi3-jakarta-spring-boot-starter	基于 OpenAPI3 规范，在 Spring Boot >= 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层基于 springdoc-openapi 项目

开发者继续使用Spring Boot 2以及OpenAPI2的规范

该starter底层依然依赖springfox项目，版本2.10.5

可以使用knife4j-openapi2-spring-boot-starter,maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi2-spring-boot-starterartifactId>
    <version>4.0.0version>
dependency>

开发者使用Spring Boot 2以及OpenAPI3规范，那需要考虑在项目的注解上做迁移变更，并且knife4j 4.0版本针对3的规范底层迁移使用springdoc-openapi项目，放弃springfox3.0

可以使用knife4j-openapi3-spring-boot-starter,maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi3-spring-boot-starterartifactId>
    <version>4.0.0version>
dependency>

支持Spring Boot 3

开发者使用Spring Boot 3以及使用OpenAPI3规范

可以使用knife4j-openapi3-jakarta-spring-boot-starter,maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
    <version>4.0.0version>
dependency>

Knife4j配置属性变化

此次Knife4j提供的Spring Boot Starter组件，增强配置属性通过spring-boot-configuration-processor工具自动生成spring-configuration-metadata.json描述性文件，因此，不同于之前的版本，配置属性会将之前的命名大写全部转为下划线

Knife4j之前的增强配置属性(老的)：

knife4j:
  enable: true
# 以setting配置为例
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true

Knife4j 4.0配置的增强属性(新的):

knife4j:
  enable: true
  setting:
    custom-code: 500
    enable-footer-custom: false
    footer-custom-content: 我是自定义的Footer

springdoc-openapi项目增强适配

Knife4j之前的版本一直都是基于springfox项目提供了增强功能，此次4.0版本针对springdoc-openapi项目也提供了增强，Knife4j提供的增强功能可以无缝在OpenAPI3的规范中使用

Knife4j独立服务工具架构升级

Knife4j在此次版本中针对聚合OpenAPI规范文档提供了独立的服务组件

整个架构重新设计，代码重写，并将该服务发布到Docker官方镜像仓库，支持不同配置中心中间件对接，数据+应用进行分离，OpenAPI的数据源可以轻松放到配置中心中，实现文档的聚合

架构图如下：

文档

Knife4j新版本文档采用新的模板，可以区分不同的版本，方便开发使用者PR贡献或者查看

4.0版本的文档作者正在疯狂码字中…….敬请期待.

示例程序

正是由于4.0的文档还在输出中，因此Knife4j在4.0新版本中也提供了不同版本的示例程序

示例如下：

• Spring Boot 2.x + OpenAPI2规范：knife4j-spring-boot27-demo
• Spring Boot 2.x +OpenAPI3规范：knife4j-springdoc-openapi-demo
• Spring Boot 3+ OpenAPI3规范：knife4j-spring-boot3-demo

 

 

整个4.0版本从确定开发方向以及迭代过程，感兴趣的朋友可以通过该issue了解：

https://gitee.com/xiaoym/knife4j/issues/I5LIQZ