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发展的可持续性,整个架构重新梳理,后续可以根据不同的需求,提供不同的服务

API

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

统一版本

在此次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的数据源可以轻松放到配置中心中,实现文档的聚合

架构图如下:

API

文档

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

API

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


打开APP阅读更多精彩内容
声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • 相关推荐
  • API

全部0条评论

快来发表一下你的评论吧 !

×
20
完善资料,
赚取积分