跳到主要内容

v4.0.0版本-2022/12/20

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-dependenciesKnife4j 提供的 dependencies 工程，引入该工程后，knife4j\springfox\swagger\springdoc-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.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

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

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

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

支持Spring Boot 3​

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

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

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</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新版本中也提供了不同版本的示例程序

示例如下：

社区​

感兴趣的朋友可以加群参与讨论贡献

关注官网底部公众号"Knife4j"，点击菜单获取加群二维码

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

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

最后由 xiaoyumin 于 更新