Spring Boot 3 整合 Knife4j：从环境搭建到 API 文档生成实战

在 Spring Boot 3 开发中，高效的 API 文档管理是前后端协作的关键。Knife4j 作为一款基于 Swagger 的增强型 API 文档工具，以其简洁的界面和强大的功能成为首选。本文将详细介绍如何在 Spring Boot 3 项目中整合 Knife4j，实现 API 文档的自动生成与可视化测试。

一、Knife4j 简介与整合优势

1. 什么是 Knife4j？

Knife4j 是为 Java 开发者量身定制的 API 文档解决方案，基于 Swagger 规范扩展，提供：

可视化文档界面：比原生 Swagger UI 更美观、操作更流畅

增强功能：支持 API 分组、参数校验提示、在线测试

轻量化：仅依赖 Swagger 核心库，无额外重量级依赖

Spring Boot 原生支持：通过 Starter 一键整合

2. 为什么选择 Knife4j？

特性	Knife4j	原生 Swagger UI
界面交互	现代化设计，支持深色模式	传统 UI，交互体验一般
文档导出	支持 Markdown/HTML/PDF	仅支持 HTML
分组管理	灵活的 API 分组策略	基于包路径简单分组
性能	优化加载速度，支持懒加载	加载速度随接口数量下降

二、环境准备

1. 创建 Spring Boot 3 项目

使用 Spring Initializr 创建项目，注意：

Java 版本：必须选择 Java 17（Spring Boot 3 最低要求）

依赖选择：勾选Spring Web和Spring Boot DevTools

2. 添加 Knife4j 依赖

在pom.xml中添加：

xml 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.2.0</version> <!-- 最新稳定版 -->
</dependency>
<!-- 排除Swagger 2.x依赖（Spring Boot 3默认集成Swagger 3.x） -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

三、核心配置：Knife4j 的初始化

1. 编写配置类

创建Knife4jConfig类，配置 API 文档信息：

kotlin 复制代码

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi // 启用OpenAPI 3.0（Spring Boot 3默认支持）
@EnableKnife4j // 启用Knife4j增强功能
public class Knife4jConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        .title("Spring Boot 3 API文档")
                        .description("基于Knife4j的前后端协作文档")
                        .version("1.0.0")
                        .build())
                .select()
                // 扫描控制器包路径（根据项目结构调整）
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                // 开启Knife4j增强功能
                .enableKnife4j();
    }
}

2. 配置文件调整（application.yml）

yaml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 解决路径匹配问题
  swagger:
    pathMapping: /api-docs # 自定义文档访问路径（可选）

四、编写测试控制器

创建UserController用于演示 API 文档生成：

less 复制代码

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Operation(summary = "获取用户详情", description = "根据用户ID查询详情")
    @GetMapping("/{id}")
    @ApiResponse(responseCode = "200", description = "用户信息", content = @Content(schema = @Schema(implementation = User.class)))
    public User getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) {
        return new User(id, "Alice", 28);
    }
    @Operation(summary = "创建用户")
    @PostMapping
    public User createUser(@RequestBody User user) {
        user.setId(System.currentTimeMillis());
        return user;
    }
    // 内部类：用户实体
    public static class User {
        private Long id;
        private String name;
        private Integer age;
        // 构造方法、Getter/Setter省略
    }
}

五、启动与验证

1. 访问文档界面

启动项目后，访问以下地址：

Knife4j 界面 ：http://localhost:8080/doc.html

OpenAPI 原始文档 ：http://localhost:8080/v3/api-docs

2. 界面功能说明

API 分组：根据包路径自动分组（可在配置类中自定义分组策略）

在线测试：点击Try it out按钮直接发送请求

参数校验：输入非法参数时自动提示（如必填项缺失）

文档导出：支持导出为 Markdown 或 PDF 格式

六、高级配置与最佳实践

1. 安全认证配置（如 JWT）

less 复制代码

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .securitySchemes(Arrays.asList(
                new SecurityScheme()
                    .name("Authorization")
                    .type(SecuritySchemeType.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")
            ))
            .securityContexts(Arrays.asList(
                SecurityContext.builder()
                    .securityReferences(Arrays.asList(
                        new SecurityReference("Authorization", new AuthorizationScope[] {})
                    ))
                    .build()
            ))
            // 其他配置...
}

2. 忽略特定接口

less 复制代码

@Operation(hidden = true) // 隐藏该接口
@GetMapping("/internal")
public String internalApi() {
    return "Internal use only";
}

3. 性能优化

生产环境关闭文档：在application-prod.yml中添加：

yaml 复制代码

spring:
  mvc:
    static-path-pattern: /**
  knife4j:
    enable: false # 关闭Knife4j

懒加载模式：在配置类中设置enable(false)，仅在开发环境启用

七、常见问题与解决方案

1. 依赖冲突

问题：启动时报ClassNotFoundException: springfox.documentation.spi.service.contexts.SecurityContext原因：Swagger 2.x 与 3.x 依赖冲突解决：确保knife4j-spring-boot-starter版本≥4.0.0，并排除旧版 Swagger 依赖。

2. 中文乱码

问题：文档中中文显示为乱码解决：在配置类中添加编码设置：

arduino 复制代码

new ApiInfoBuilder()
    .contact(new Contact("你的团队", "", "[email protected]"))
    .build();

3. 路径匹配失败

问题：无法访问doc.html页面解决：检查RequestHandlerSelectors扫描路径是否正确，或尝试清除浏览器缓存。

总结

通过以上步骤，我们完成了 Spring Boot 3 与 Knife4j 的整合，实现了：

自动化 API 文档生成与可视化

在线接口测试与参数校验

灵活的分组管理与安全配置

Knife4j 在 Spring Boot 3 中的表现更加轻量高效，尤其适合微服务架构和前后端分离项目。建议在开发阶段充分利用其文档功能，减少联调成本；在生产环境中关闭文档界面，确保系统安全。

扩展阅读：

Knife4j 官方文档

Spring Boot 3 迁移指南

OpenAPI 3.0 规范