首页 > 软件编程 > java > SpringBoot集成Knife4j/Swagger

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

2026-03-30 10:06:49 作者：翘着二郎腿的程序猿

本文将详细讲解SpringBoot如何快速集成Knife4j/Swagger,从环境搭建、基础配置、接口注解使用,到进阶优化,全程附完整代码示例,感兴趣的朋友跟随小编一起看看吧

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

而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核心依赖，避免版本冲突）。

<!-- 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实例。

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注解：

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注解：

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文档地址（默认地址，无需修改）：

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），可在配置类中添加全局参数，无需在每个接口单独添加：

// 在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过滤：

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

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

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

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4. 生产环境关闭Swagger文档

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

# application-dev.yml（开发环境，开启）
knife4j:
  enable: true
# application-prod.yml（生产环境，关闭）
knife4j:
  enable: false

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

@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项目中吧！

到此这篇关于SpringBoot集成Knife4j/Swagger:接口文档自动生成,告别手写API文档的文章就介绍到这了,更多相关SpringBoot集成Knife4j/Swagger内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！