SpringBoot集成Knife4j/Swagger：接口文档自动生成，告别手写API文档

作为后端开发者，接口文档编写是绕不开的工作------既要保证文档的准确性、完整性，又要及时同步接口变更，手动编写不仅耗时耗力，还容易出现"接口与文档不一致"的问题，给前后端联调带来极大困扰。

而Swagger正是解决这一痛点的利器，它能自动扫描项目中的接口，生成标准化的API文档，支持在线调试、接口描述、参数校验等功能；而Knife4j则是Swagger的增强版，基于Swagger封装，优化了UI界面，增加了更多实用功能（如接口排序、导出文档、接口加密等），更贴合国内开发者的使用习惯。

本文将详细讲解SpringBoot如何快速集成Knife4j/Swagger，从环境搭建、基础配置、接口注解使用，到进阶优化，全程附完整代码示例，新手也能快速上手，彻底告别手写API文档的烦恼！

一、核心优势：为什么选择Knife4j而非原生Swagger？

原生Swagger功能足够基础，但UI界面简陋、交互体验一般，而Knife4j作为增强版，完美解决了这些问题，核心优势如下：

UI更美观，交互更友好：替换原生Swagger的简陋界面，采用现代化设计，支持接口搜索、分类、排序，操作更流畅。
功能更强大：支持接口文档导出（PDF/Markdown/HTML）、接口调试参数记忆、接口加密、全局参数配置等原生Swagger没有的功能。
配置更简洁：基于SpringBoot自动配置，无需复杂XML配置，几行代码即可完成集成。
兼容性更好：完美兼容SpringBoot 2.x、3.x版本，支持JDK8及以上，适配主流的Spring全家桶。

简单来说：Knife4j = Swagger + 更优UI + 更多实用功能，是SpringBoot项目接口文档的首选方案。

二、环境准备

本次集成基于以下环境，其他版本可灵活适配（文末附版本兼容说明）：

SpringBoot版本：2.7.10（兼容2.x、3.x，3.x配置略有差异，下文会说明）
Knife4j版本：4.5.0（最新稳定版）
JDK版本：1.8及以上
开发工具：IDEA

三、SpringBoot集成Knife4j/Swagger（步骤详解）

集成过程分为3步：添加依赖 → 编写配置类 → 接口添加注解，全程无复杂操作，直接复制代码即可。

步骤1：添加Maven依赖

在pom.xml中添加Knife4j的依赖，无需额外添加Swagger依赖（Knife4j已内置Swagger核心依赖，避免版本冲突）。

xml 复制代码

<!-- Knife4j Swagger 增强版依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

<!-- 若使用SpringBoot 3.x，需替换为以下依赖（适配Jakarta EE） -->
<!-- <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.5.0</version>
    <exclusions>
        <exclusion>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency> -->

注意：SpringBoot 3.x版本需排除javax.servlet-api依赖，因为3.x已使用Jakarta EE的jakarta.servlet-api，避免依赖冲突。

步骤2：编写Swagger配置类

创建一个配置类，用于配置Swagger的基础信息（如文档标题、作者、版本）、扫描的接口包、全局参数等。该类需添加@Configuration注解，注入Docket实例。

java 复制代码

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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Knife4j/Swagger 配置类
 */
@Configuration
@EnableOpenApi // 开启Swagger文档（SpringBoot 3.x无需额外添加，2.x需添加）
public class SwaggerConfig {

    /**
     * 配置Docket实例，指定接口文档的基本信息和扫描规则
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // OAS_30对应Swagger3.0规范，推荐使用
                .apiInfo(apiInfo()) // 配置文档基础信息
                .select()
                // 扫描指定包下的接口（替换为你的接口所在包路径）
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                // 扫描所有接口（不推荐，建议指定包）
                // .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()) // 匹配所有接口路径
                .build();
    }

    /**
     * 配置文档的基础信息（标题、作者、版本、描述等）
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot + Knife4j/Swagger 接口文档") // 文档标题
                .description("本文档用于前后端联调，自动生成接口信息，无需手写") // 文档描述
                .contact(new Contact("开发者", "https://blog.csdn.net", "xxx@163.com")) // 作者信息（姓名、博客地址、邮箱）
                .version("1.0.0") // 文档版本
                .build();
    }
}

关键说明：

@EnableOpenApi：开启Swagger文档功能，SpringBoot 2.x必须添加，3.x版本可省略（Knife4j自动开启）。
basePackage：必须替换为你项目中Controller所在的包路径，否则Swagger无法扫描到接口。
DocumentationType.OAS_30：使用Swagger3.0规范，是目前的主流版本，兼容Knife4j的所有功能。

步骤3：接口添加Swagger注解（核心）

Swagger通过注解识别接口信息，为Controller、接口方法、参数添加注解，即可自动生成详细的接口文档。以下是常用注解及示例：

常用注解说明

注解	作用范围	说明
@Api	Controller类	描述Controller的作用（如"用户管理接口"）
@ApiOperation	接口方法	描述接口的功能（如"查询用户列表"）
@ApiParam	接口参数	描述参数的含义、是否必填、默认值等
@ApiModel	实体类	描述实体类的作用（如"用户实体"）
@ApiModelProperty	实体类字段	描述字段的含义、数据类型、是否必填等
@ApiIgnore	Controller/方法/参数	忽略该接口/参数，不生成到文档中

实战示例（Controller + 实体类）

首先创建实体类（User），添加@ApiModel和@ApiModelProperty注解：

java 复制代码

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * 用户实体类
 */
@Data
@ApiModel(value = "User", description = "用户实体")
public class User {

    @ApiModelProperty(value = "用户ID", example = "1", required = false)
    private Long id;

    @ApiModelProperty(value = "用户名", example = "zhangsan", required = true)
    private String username;

    @ApiModelProperty(value = "用户密码", example = "123456", required = true)
    private String password;

    @ApiModelProperty(value = "用户年龄", example = "20", required = false)
    private Integer age;
}

然后创建Controller，添加@Api、@ApiOperation、@ApiParam注解：

java 复制代码

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * 用户管理接口
 */
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理接口", description = "提供用户的增删改查操作")
public class UserController {

    // 模拟数据库数据
    private static final List<User> userList = new ArrayList<>();

    static {
        userList.add(new User(1L, "zhangsan", "123456", 20));
        userList.add(new User(2L, "lisi", "654321", 22));
    }

    /**
     * 查询所有用户
     */
    @GetMapping("/list")
    @ApiOperation(value = "查询用户列表", notes = "获取所有用户的详细信息")
    public List<User> getUserList() {
        return userList;
    }

    /**
     * 根据ID查询用户
     */
    @GetMapping("/{id}")
    @ApiOperation(value = "根据ID查询用户", notes = "传入用户ID，获取单个用户信息")
    public User getUserById(@ApiParam(value = "用户ID", required = true, example = "1") @PathVariable Long id) {
        return userList.stream().filter(user -> user.getId().equals(id)).findFirst().orElse(null);
    }

    /**
     * 添加用户
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户", notes = "传入用户信息，新增用户")
    public String addUser(@ApiParam(value = "用户信息", required = true) @RequestBody User user) {
        userList.add(user);
        return "添加成功";
    }

    /**
     * 修改用户
     */
    @PutMapping("/update")
    @ApiOperation(value = "修改用户", notes = "传入用户ID和新信息，修改用户")
    public String updateUser(@ApiParam(value = "用户信息", required = true) @RequestBody User user) {
        userList.replaceAll(u -> u.getId().equals(user.getId()) ? user : u);
        return "修改成功";
    }

    /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "传入用户ID，删除指定用户")
    public String deleteUser(@ApiParam(value = "用户ID", required = true, example = "1") @PathVariable Long id) {
        userList.removeIf(user -> user.getId().equals(id));
        return "删除成功";
    }
}

四、启动项目，访问Knife4j文档

启动SpringBoot项目，确保项目无报错；
访问Knife4j文档地址（默认地址，无需修改）：

text 复制代码

http://localhost:8080/doc.html

（注：若项目配置了server.port，需替换为你的端口号；若配置了上下文路径，需添加上下文路径，如http://localhost:8080/demo/doc.html）

文档界面说明

访问成功后，将看到Knife4j的可视化界面，主要分为3个部分：

左侧：接口分类（按Controller分组），可搜索、折叠接口；
中间：接口详情（请求方式、参数、返回值、示例等）；
右侧：在线调试（可直接填写参数，发送请求，查看响应结果，无需借助Postman）。

核心功能：

在线调试：填写参数后，点击"发送"即可测试接口，支持GET、POST、PUT、DELETE等所有请求方式；
文档导出：点击界面顶部"导出"按钮，可导出PDF、Markdown、HTML格式的接口文档，方便离线查看；
参数校验：接口参数的必填项、示例值会自动显示，减少前后端联调的沟通成本。

五、进阶配置（优化体验，避坑指南）

以下配置可根据项目需求选择性添加，进一步优化Knife4j/Swagger的使用体验，避免常见坑。

1. 全局参数配置（如Token、Authorization）

若项目接口需要登录认证（如Token），可在配置类中添加全局参数，无需在每个接口单独添加：

java 复制代码

// 在SwaggerConfig的createRestApi方法中添加
.addGlobalParameters(Collections.singletonList(
        new ParameterBuilder()
                .name("Authorization") // 参数名
                .description("令牌（格式：Bearer token）") // 参数描述
                .in(ParameterType.HEADER) // 参数位置（HEADER/QUERY/PATH）
                .required(false) // 是否必填（根据项目需求调整）
                .schema(new Schema<String>().type("string"))
                .build()
))

2. 忽略指定接口/路径

若某些接口（如登录接口、错误页接口）不需要生成文档，可通过以下方式忽略：

方式1：在接口方法上添加@ApiIgnore注解；
方式2：在配置类中通过paths过滤：

java 复制代码

// 排除/login和/error接口
.paths(PathSelectors.regex("^(?!/login|/error).*$"))

3. 解决SpringBoot 2.6.x+ 版本冲突问题

SpringBoot 2.6.x及以上版本，默认的路径匹配策略发生变化，会导致Swagger启动报错，需在application.yml中添加以下配置：

yaml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4. 生产环境关闭Swagger文档

Swagger文档仅用于开发和测试环境，生产环境需关闭，避免接口暴露带来安全风险。可通过配置文件控制：

yaml 复制代码

# application-dev.yml（开发环境，开启）
knife4j:
  enable: true

# application-prod.yml（生产环境，关闭）
knife4j:
  enable: false

同时，在配置类中添加条件注解，根据环境动态开启/关闭：

java 复制代码

@Configuration
@EnableOpenApi
@ConditionalOnProperty(prefix = "knife4j", name = "enable", havingValue = "true")
public class SwaggerConfig {
    // 配置内容不变
}

六、常见问题与解决方案

问题1：启动项目后，访问/doc.html报404

解决方案：1. 检查Controller包路径是否配置正确（basePackage）；2. 检查Knife4j依赖是否添加成功；3. 若使用SpringBoot 2.6.x+，检查是否添加了路径匹配策略配置。
问题2：接口文档中没有显示实体类参数

解决方案：确保实体类添加了@ApiModel和@ApiModelProperty注解，且接口参数使用@RequestBody接收实体类。
问题3：SpringBoot 3.x启动报错，提示javax.servlet相关错误

解决方案：排除Knife4j依赖中的javax.servlet-api，使用Jakarta EE的依赖（参考步骤1的依赖配置）。
问题4：在线调试时，响应结果乱码

解决方案：在application.yml中配置字符编码：
spring: http: encoding: charset: UTF-8 force: true

七、总结

SpringBoot集成Knife4j/Swagger，仅需3步即可实现接口文档的自动生成，彻底告别手写文档的繁琐工作，大幅提升前后端联调效率。

本文从基础集成、注解使用，到进阶配置、避坑指南，覆盖了开发中常用的所有场景，新手可直接复制代码上手，资深开发者可根据项目需求进行个性化配置。

核心要点：

Knife4j是Swagger的增强版，UI更友好、功能更强大；
核心是通过注解（@Api、@ApiOperation等）描述接口信息，Swagger自动扫描生成文档；
生产环境必须关闭Swagger，避免安全风险；
SpringBoot 2.x和3.x配置略有差异，需注意依赖和注解的适配。

掌握Knife4j/Swagger的使用，能让后端开发者从繁琐的文档编写中解放出来，专注于核心业务逻辑开发，提升整体开发效率。赶紧动手集成到你的SpringBoot项目中吧！