Knife4j 4.0版本升级指南：全面拥抱OpenAPI3规范-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01055/article/details/148527238

Knife4j 4.0版本升级指南：全面拥抱OpenAPI3规范

knife4j Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution 项目地址: https://gitcode.com/gh_mirrors/kn/knife4j

项目概述

Knife4j是一款强大的API文档增强工具，基于Swagger/OpenAPI规范为开发者提供更丰富的文档展示和调试功能。随着4.0版本的发布，Knife4j在项目结构、功能支持和规范适配等方面都进行了重大升级。

新版项目结构解析

4.0版本对项目模块进行了重新规划，主要分为以下几类：

核心模块：
- knife4j-core：提供核心工具类和增强注解
- knife4j-dependencies：统一管理依赖版本
UI展示模块：
- knife4j-openapi2-ui：支持OpenAPI2规范的纯前端UI
- knife4j-openapi3-ui：支持OpenAPI3规范的纯前端UI
Spring Boot集成模块：
- 针对OpenAPI2规范的starter
- 针对OpenAPI3规范的starter（分Spring Boot 2和3两个版本）
高级功能模块：
- 网关聚合组件
- 服务聚合中间件

Spring Boot 2.x项目升级方案

OpenAPI2规范升级

对于仍在使用传统Swagger（OpenAPI2）规范的项目：

依赖变更：

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

注意事项：
- 底层依赖springfox 2.10.5版本
- 不支持springfox 3.x版本
- 建议尽快迁移到OpenAPI3规范

OpenAPI3规范升级

对于已迁移到OpenAPI3规范的项目：

依赖配置：

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

技术特点：
- 底层基于springdoc-openapi项目
- 提供完整的增强功能支持
- 与OpenAPI3规范完全兼容

Spring Boot 3.x项目支持

针对Spring Boot 3.x的新特性：

环境要求：
- JDK版本≥17
- 必须使用Jakarta EE规范

依赖配置：

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

技术特点：
- 底层依赖springdoc-openapi 2.x
- 完全适配Spring Boot 3.x生态
- 提供与之前版本一致的增强功能

网关聚合功能详解

4.0版本新增了针对Spring Cloud Gateway的文档聚合功能：

基本配置

knife4j:
  gateway:
    enable: true
    routes:
      - name: 用户服务
        url: /user-service/v2/api-docs?group=default
        service-name: user-service
        order: 2

配置参数说明

| 参数 | 类型 | 说明 | 必填 | |------|------|------|------| | enable | Boolean | 是否启用网关聚合 | 是 | | routes | List | 聚合服务列表 | 是 | | routes[].name | String | 服务显示名称 | 是 | | routes[].url | String | 文档接口地址 | 是 | | routes[].service-name | String | 服务标识名称 | 否 | | routes[].order | Integer | 显示排序 | 否 |

使用建议

网关前缀需要包含在url配置中
支持动态配置更新（如结合Nacos配置中心）
支持Swagger2和OpenAPI3规范的文档聚合

升级建议与最佳实践

规范迁移策略：
- 新项目直接采用OpenAPI3规范
- 老项目逐步迁移，先升级Knife4j版本，再迁移规范
版本兼容性：
- Spring Boot 2.4以下版本建议使用Knife4j 3.x
- Spring Boot 2.4-3.0之间使用4.0版本
- Spring Boot 3.0+必须使用Jakarta版本
功能选择：
- 单体项目直接使用对应规范的starter
- 微服务架构考虑使用网关聚合功能
- 复杂场景可使用聚合中间件