当前位置:

首页 > 编程开发 > SpringBoot3.5集成Knife4j4.3的详细步骤

SpringBoot3.5集成Knife4j4.3的详细步骤

SpringBoot3.5集成Knife4j4.3替代停更的SpringFox,基于OpenAPI3规范与SpringDoc,只需引入一个starter依赖并配置,即可实现自动生成接口文档、在线调试、离线导出及UI增强。支持单体和SpringCloudGateway聚合,注解改用Jakarta命名空间,简化开发流程并提升API管理效率。

本文目录

    避坑指南:还在用 SpringFox?快换成这位“天选之子”吧!

    有没有过这种场景:兴冲冲地把 Spring Boot 2 升级到 Spring Boot 3,一启动,嘿,项目跑起来了!正准备给自己点个赞,结果一打开 Swagger 页面——404 空白。

    这时候才反应过来:当年陪我们闯过无数 CRUD 日夜的 SpringFox,早在 2020 年就悄悄停更了。它不仅跟不上 OpenAPI 3 的新潮规范,更致命的是,它底层死死抱住的 ja vax.* 包,在 Spring Boot 3 时代已经被彻底连根拔起,换成了 jakarta.* 。

    简单来说,这不是代码写得有问题,而是时代的眼泪。面对这种版本刺客,硬刚肯定不现实。既然官宣分手,就得收拾心情,寻找新的幸福——也就是今天的主角:SpringDoc。而 Knife4j 的底层就是 SpringDoc。

    为什么说它是“天选之子”?

    • 无缝衔接:基于 OpenAPI 3 规范量身定制,对 Spring Boot 3 甚至 WebFlux 都是原生级支持,丝滑得就像德芙。
    • 极简主义:以前用 SpringFox 时,那一堆繁琐的 Docket 配置是不是很头疼?换成 SpringDoc 后,很多时候只需要引入一个 Starter 依赖,连配置文件都不用写就能直接起飞。
    • 社区活跃:不像前任那样玩失踪,SpringDoc 社区更新非常活跃,遇到 Bug 也有人管,这才是长长久久的靠谱之选。

    一、 核心组件与关系介绍

    在微服务架构中,API 文档工具通常可以分为三个层次:“规范”、“生成器”和“展示层”。它们的分工与关系,简单梳理一下:

    组件

    角色定位

    核心作用

    与 Knife4j 的关系

    Swagger (OpenAPI 3)

    接口规范

    定义了一套用于描述 API 接口的标准(如路径、参数、返回值)。

    Knife4j 完全遵循 OpenAPI 3.0 规范生成文档。

    SpringDoc

    规范实现

    扫描 Spring Boot 代码中的注解 (如 @Tag, @Operation) ,自动生成符合 OpenAPI 规范的 JSON 数据。

    SpringDoc 自带原生 Swagger UI。

    底层依赖。Knife4j 4.x 已内置 SpringDoc,负责数据的生产。

    Knife4j

    UI 增强层

    基于 SpringDoc 提供的数据,渲染出美观、交互性更强的文档界面。

    上层封装。在 SpringDoc 基础上提供了文档增强、离线导出等功能。

    二、 Knife4j 简介与资源

    Knife4j 是一个为 Ja va MVC 框架集成 Swagger 生成 API 文档的增强解决方案。它的前身是 swagger-bootstrap-ui,目的就是提供更符合国人习惯的接口文档体验。

    • 核心作用:
      1. 文档说明:根据代码注解自动生成接口文档,连请求和响应示例都给你安排得明明白白。
      2. 在线调试:提供强大的接口调试功能,支持全局参数、动态参数修改。
      3. 离线文档:支持导出 Markdown、HTML、Word 等格式的离线文档,方便交付。
      4. 界面优化:提供现代化的 UI 界面,支持深色模式、接口搜索与排序。
    • 官方资源:
      • 官方文档:https://doc.xiaominfo.com/
      • 源码地址:https://gitee.com/xiaoym/knife4j

    SpringBoot3.5集成Knife4j4.3的详细步骤

    三、 Spring Boot 3.5 单体应用集成步骤

    1. 环境准备

    • JDK:17 及以上(Spring Boot 3.x 强制要求)
    • Spring Boot:3.5.9
    • Knife4j:4.3.0

    2. 引入 Ma ven 依赖

    在 pom.xml 中加一个依赖。这个依赖已经内置 SpringDoc,所以不需要再单独引入 Swagger 相关包。

    
        com.github.xiaoymin
        knife4j-openapi3-jakarta-spring-boot-starter
        4.3.0
    

    来看看这个依赖包里包含了哪些子依赖:

    依赖包

    描述

    核心作用

    knife4j-openapi3-ui

    Knife4j 的 UI 核心

    提供增强的 Web 界面 (/doc.html),包含文档渲染、接口调试、全局参数、离线导出等功能。

    knife4j-core

    Knife4j 工具模块

    提供工具类、模型定义、核心工具链等底层支持。

    springdoc-openapi-starter-webmvc-ui

    SpringDoc WebMVC 集成与 UI

    提供原生的 Swagger UI (/swagger-ui.html),是 SpringDoc 自动配置的入口。

    springdoc-openapi-starter-webmvc-api

    SpringDoc WebMvc API 支持

    提供对 Spring WebMVC 的底层支持,包含请求/响应处理、参数解析等。

    springdoc-openapi-starter-webmvc-common

    SpringDoc WebMvc 通用模块

    包含 SpringDoc 的通用工具类和核心逻辑,是 API 模块的基础。

    swagger-annotations-jakarta

    OpenAPI 注解库 (Jakarta)

    提供 jakarta命名空间版本的 OpenAPI 注解,如 @Tag, @Operation, @Schema等。

    swagger-models-jakarta

    OpenAPI 模型库 (Jakarta)

    提供 jakarta命名空间版本的 OpenAPI 数据模型,如 Info, Contact, OpenAPI等。

    swagger-ui

    Swagger UI 前端资源

    包含 Swagger UI 的所有前端静态资源(HTML, JS, CSS),被 springdoc-openapi-starter-webmvc-ui所依赖。

    3. 配置文件 (application.yml)

    配置 SpringDoc 的扫描规则和 Knife4j 的增强特性。

    # SpringDoc 原生配置
    springdoc:
      swagger-ui:
        enabled: true
        path: /swagger-ui.html
        tags-sorter: alpha
        operations-sorter: alpha
      api-docs:
        enabled: true
        path: /v3/api-docs
      group-configs:
        - group: default
          paths-to-match: '/**'
          packages-to-scan: com.example.controller
    # Knife4j 增强配置
    knife4j:
      enable: true
      setting:
        language: zh_cn
        enable-swagger-models: true
        swagger-model-name: 实体类列表

    4. 初始化配置 @Configuration

    /**
     * OpenApi3在线接口文档组件初始化
     */
    @Slf4j
    @Configuration(proxyBeanMethods = false)
    @ConditionalOnProperty(name = "springdoc.api-docs.enabled", matchIfMissing = true)
    public class OpenApi3Config {
        @Bean
        public OpenAPI springDocOpenAPI() { 
            return new OpenAPI(SpecVersion.V30).info(new Info()
                                                     .title("API文档")
                                                     .description("简介")
                                                     .version("v1.0"))
            // 配置Authorizations
            .components(new Components()
                        .addSecuritySchemes("Authorization", new SecurityScheme().name("Authorization").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY))
                        .addSecuritySchemes("TenandId", new SecurityScheme().name("TenandId").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY)));
        } 
    }

    5. 注解示例

    Spring Boot 3.x 使用 OpenAPI 3 规范注解,和旧版 Swagger 2 差别不小。

    注解

    作用位置

    描述

    示例/替代旧注解

    @Tag

    Controller 类

    API 分组标签

    替代 @Api

    @Operation

    Controller 方法

    单个接口的详细描述

    替代 @ApiOperation

    @Parameter

    方法参数

    描述单个参数

    替代 @ApiParam

    @Schema

    模型类/字段

    描述数据模型/字段

    替代 @ApiModel, @ApiModelProperty

    @Parameters

    方法

    多个参数的容器

    包含多个 @Parameter

    控制器Controller

    import io.swagger.v3.oas.annotations.Operation;
    import io.swagger.v3.oas.annotations.Parameter;
    import io.swagger.v3.oas.annotations.tags.Tag;
    @RestController
    @RequestMapping("/api/users")
    @Tag(name = "用户管理")
    public class UserController {
        @GetMapping("/{id}")
        @Operation(summary = "根据ID查询用户")
        public String getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) {
            return "User " + id;
        }
    }

    实体Bean

    @Schema(description = "用户信息")
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor 
    public class UserInfo   { 
        /**
    	 * 中文名
    	 */
    	@Schema(description = "中文名") 
    	private String name;
    }

    6 访问验证

    启动项目后,访问以下地址:

    • Knife4j 文档地址:http://localhost:8080/doc.html
    • 原生 Swagger 地址:http://localhost:8080/swagger-ui.html

    效果图

    SpringBoot3.5集成Knife4j4.3的详细步骤

    四、 Spring Cloud Gateway 集成方案

    在微服务架构中,通常希望在网关层聚合所有微服务的接口文档,这样就不用挨个去访问子服务了。

    1. 网关服务 (Gateway) 配置

    在 Gateway 模块中引入聚合依赖:

    
        com.github.xiaoymin
        knife4j-gateway-spring-boot-starter
        4.3.0
    
    
    
        org.springdoc
        springdoc-openapi-starter-webflux-api
        2.8.15 
    
    
        org.springframework.cloud
        spring-cloud-starter-gateway-server-webflux
        4.3.3 
    

    在 application.yml 中开启服务发现模式聚合:

    # 第二种配置方式:自动发现
    knife4j:
      gateway:
        enabled: true
        # 指定聚合模式为服务发现(基于注册中心如 Nacos/Eureka)
        strategy: discover
        discover:
          enabled: true
          version: openapi3
    # 第二种配置方式:手动配置
    knife4j:
      gateway:
        enabled: true
        strategy: manual
        operations-sorter: order
        routes:
          - name: 用户服务
            context-path: /user
            url: /user/v3/api-docs/default
          - name: 订单管理
            context-path: /order
            url: /order/v3/api-docs/default

    2. 子微服务 (Service) 配置

    确保每个业务微服务都按照 第三部分 的步骤引入了 knife4j-openapi3-jakarta-spring-boot-starter 并正确配置了 packages-to-scan。

    3. 访问方式

    启动网关和各个微服务后,直接访问 网关的地址 即可查看聚合文档:

    http://网关IP:网关端口/doc.html

    效果图

    SpringBoot3.5集成Knife4j4.3的详细步骤

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    QQ影音怎么加速播放视频课程
    QQ影音怎么加速播放视频课程

    播放时右键选播放速度,或点控制条倍速,1.25 到 1.5 倍看课最舒服;公式代码类内容别超过 1.25 倍。

    企业微信创建企业提示失败怎么办 实名与填写检查
    企业微信创建企业提示失败怎么办 实名与填写检查

    先看提示属于哪类:名称占用就加后缀,实名不一致就重填本人信息,证件不清晰就重拍。统一社会信用代码逐位核对,连续三次失败别改材料重投,直接联系客服人工核。

    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?
    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?

    说明源码提交对字符串、生成器和数组的识别边界,以及扫描命令与发行包核验限制。

    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?
    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?

    0.170.0 的语音更新限于终端通话协商能力的明确新增,同名工具服务器跨环境支持仍标注实验性质;连接部分则修复大请求回退、认证竞态和云端重连等具体问题。这份正式版公告不足以证明所有账户、所有客户端都已具备完整语音功能。

    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?
    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?

    了解Hy4 flash、FP8与base的适用任务,阅读官方安装及图文代码,并核对资源和MaaS许可条件。

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化
    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化。说明已核实的更新范围、类型兼容性和本地版本确认方法。

    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?
    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?

    OpenAI Java SDK 4.108.0 面向 Live MCP 工具接入与 Managed Agents 预算状态处理,说明新增模型、事件含义、正式发布范围和适用限制。

    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?
    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?

    Free Claude Code 6.19.37 在自动搜索时保留客户端工具及选择条件,代理执行搜索后仍返回普通调用。说明适用场景、历史信息保留、请求约束与第三方项目的版本边界。

    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?
    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?

    Google GenAI Go SDK 1.78.0 将 Gemini Developer API 默认改为 v1,可用 HTTPOptions.APIVersion 或环境变量保留 v1beta,Vertex AI 默认值不变。

    Google GenAI SDK 3.5.0实时交互值得哪些项目升级评估?
    Google GenAI SDK 3.5.0实时交互值得哪些项目升级评估?

    解释实验性实时支持、环境检查与生产评估中需要验证的条件。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。