SpringBoot接口文档神器：Swagger与Knife4j整合指南

原创于 2025-09-18 13:39:33 发布 · 1.3k 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java

Spring相关框架学习专栏收录该内容

11 篇文章

订阅专栏

该文章已生成可运行项目，

开篇：为什么需要接口工具？先解决 3 个痛点

后端写接口、前端调接口、测试测接口，最头疼的就是 “文档”：

手写文档：花 1 小时写，改接口后忘了更，前端对接时发现 “文档和代码不一样”；
调试麻烦：用 Postman 要手动填 URL、参数、请求头，效率低；
协作混乱：后端说 “参数是 phone”，前端传 “mobile”，互相扯皮。

Swagger 和 Knife4j 就是解决这些问题的 “神器”：Swagger 是基础框架，自动生成接口文档；Knife4j 是增强版，UI 更漂亮、功能更强大。这篇手把手教你整合，小白跟着做，接口对接效率提升 10 倍！

一、基础款：Swagger—— 自动生成接口文档的 “基石”

1. 先搞懂：Swagger 是什么？

Swagger 是一个RESTful 接口的文档生成与测试工具，核心功能：

📖自动生成文档：写代码时加注解，网页上自动显示接口信息（不用手动写文档）；
可视化界面：网页版界面，清晰展示接口 URL、参数、返回值；
🧪 在线调试：直接在网页上填参数、发请求、看响应，不用 Postman；
🔄团队协作：后端、前端、测试共用一套实时更新的文档，避免信息差。

2. SpringBoot 整合 Swagger（3 步搞定）

步骤 1：引入依赖（pom.xml）
直接复制粘贴，注意版本是2.9.2（稳定版）：

<!-- Swagger核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- Swagger可视化界面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

步骤 2：写配置类（核心）
创建SwaggerConfig.java，放在config包下:

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

@Configuration  // 标记为Spring配置类
@EnableSwagger2  // 开启Swagger功能（必须加，否则不生效）
public class SwaggerConfig {

    /**
     * Docket：Swagger的核心配置对象，控制文档生成规则
     */
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定Swagger版本为2.0
                .apiInfo(buildApiInfo()) // 配置文档的基本信息（标题、作者等）
                .select() // 开始配置接口扫描范围
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描哪个包下的接口（填你的项目包名）
                .paths(PathSelectors.any()) // 扫描该包下的所有接口（any()=全部，也可写PathSelectors.ant("/api/**")只扫/api开头的）
                .build();
    }

    /**
     * 配置文档的基本信息（显示在Swagger网页顶部）
     */
    private springfox.documentation.service.ApiInfo buildApiInfo() {
        // 作者信息（姓名、个人网址、邮箱，可选）
        Contact contact = new Contact("技术团队", "https://www.example.com", "tech@example.com");
        
        return new ApiInfoBuilder()
                .title("企业管理系统API文档") // 文档标题
                .description("企业管理系统接口文档说明") // 文档描述
                .contact(contact) // 作者信息
                .version("1.0.0") // 文档版本
                .build();
    }
}

步骤 3：特殊配置（仅自定义 Starter 需要）
spring.factories配置，普通 SpringBoot 项目不用加！这是把 Swagger 封装成 “公共组件（比如公司内部的Starter）” 时，让 Spring 自动扫描配置类的方式。
如果你的项目是普通 SpringBoot 应用，跳过这步；如果是封装 Starter，才需要在src/main/resources/META-INF/spring.factories中加：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.config.SwaggerConfiguration  # 填你的Swagger配置类全路径

3. 核心用法：用注解美化接口文档

Swagger 的文档之所以清晰，全靠注解。3 个最常用的注解，直接上示例：

（1）Controller 类上：`@Api`（分类接口）

给接口分个类，比如 “app 端用户登录”，网页上会按分类展示：

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RestController;

// value：分类描述；tags：分类名称（网页上显示的大标题）
@Api(value = "app端用户登录", tags = "app端用户登录")
@RestController
public class ApUserLoginController {
    // 接口方法写这里...
}

（2）接口方法上：`@ApiOperation`（描述功能）

说明这个接口是干嘛的，比如 “用户登录”：
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@ApiOperation("用户登录：输入手机号和验证码，返回token") // 接口功能描述
@PostMapping("/api/login")
public ResponseResult login(@RequestBody LoginDto dto) {
    // 业务逻辑：校验验证码、生成token
    return ResponseResult.success("token: abc123456");
}

（3）POJO 类上：`@ApiModelProperty`（描述参数）

说明请求参数的含义、是否必填，比如登录的手机号和验证码：

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

@Data
public class LoginDto {
    // value：参数描述；required：是否必填（必填项会标红提示）；example：示例值
    @ApiModelProperty(value = "手机号", required = true, example = "13800138000")
    private String phone;

    @ApiModelProperty(value = "验证码", required = true, example = "666666")
    private String code;
}

4. 访问与调试：网页上直接用

（1）启动项目，访问地址：http://ip:port/swagger-ui.html
比如本地项目端口是 8080，就访问：http://localhost:8080/swagger-ui.html
（2）在线调试接口（以登录为例）

点击 “app 端用户登录” 分类，展开/api/login接口；
点击 “Try it out”（展开调试面板）；
在Request body里填参数（示例值会自动填充，可修改）；
点击 “Execute” 发送请求，下方会显示响应结果（比如返回的 token）。

二、增强款：Knife4j——Swagger 的 “颜值与功能担当”

1. 为什么选 Knife4j？比 Swagger 强在哪？

Knife4j 是Swagger 的增强解决方案（前身是 swagger-bootstrap-ui），简单说就是 “Swagger 的内核 + 更漂亮的 UI + 更多实用功能”。

官方资源：

Gitee地址：https://gitee.com/xiaoym/knife4j
官方文档：https://doc.xiaominfo.com
在线演示：http://knife4j.xiaominfo.com/doc.html

核心优势：

📊 UI 更友好：比 Swagger 的默认界面清晰，支持接口排序、搜索；
🔧功能更全：支持离线文档导出（Markdown/HTML/PDF）、参数过滤、动态参数；
配置更简单：引入一个依赖就够，不用额外导 UI 包。

2. SpringBoot 整合 Knife4j（3 步搞定）

步骤 1：引入依赖（pom.xml）
注意：用了 Knife4j 就不用再导 Swagger 的依赖了，它已经包含了

<!-- Knife4j依赖（包含Swagger核心+增强UI） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version> <!-- 稳定版，适配SpringBoot 2.7+ -->
</dependency>

步骤 2：写配置类（多了一个注解）
和 Swagger 的配置差不多，只多了@EnableKnife4j注解（开启增强功能）：

@Configuration
@EnableSwagger2  // 兼容Swagger核心功能
@EnableKnife4j   // 开启Knife4j增强功能（必须加，否则没有增强UI）
public class Swagger2Configuration {

    /**
     * defaultApi2：配置接口文档的分组（多个分组可区分不同模块）
     */
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .groupName("1.0版本") // 分组名称（比如按版本分，1.0/2.0）
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描的包路径
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes()) // 添加安全配置
                .securityContexts(securityContexts());;
    }

   private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
                .title("企业管理系统API文档")
                .description("Knife4j增强版接口文档")
                .termsOfServiceUrl("https://www.example.com/")
                .contact(new Contact("技术团队", "https://www.example.com", "tech@example.com"))
                .version("1.0")
                .build();
    }
    
    // 配置认证方式（JWT示例）
    private List<ApiKey> securitySchemes() {
        return Collections.singletonList(
            new ApiKey("Authorization", "Authorization", "header")
        );
    }
    
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
            SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build()
        );
    }
    
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        return Collections.singletonList(
            new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope})
        );
    }
}

步骤 3：特殊配置（同 Swagger）
如果是封装 Starter，在spring.factories中加配置类全路径：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.heima.common.swagger.Swagger2Configuration

3. 访问与核心功能体验

（1）启动项目，访问地址
Knife4j 的访问路径和 Swagger 不一样，是/doc.html：http://ip:port/doc.html
比如本地访问：http://localhost:8080/doc.html

（2）必试的 3 个增强功能

接口排序：在 Controller 类上加@ApiSort(1)（数字越小越靠前），能按业务顺序展示接口，不用翻来翻去；
离线文档导出：点击页面顶部 “文档下载”，可导出 Markdown、HTML、PDF 格式的文档，方便离线查看；
参数过滤：调试接口时，可隐藏不需要的参数（比如公共请求头），界面更清爽。

三、小白避坑指南：常见问题及解决

1. 访问页面 404？

检查注解：Swagger 必须加@EnableSwagger2，Knife4j 必须加@EnableKnife4j；
检查包路径：RequestHandlerSelectors.basePackage(“com.heima”)必须包含你的 Controller 包；
SpringBoot 版本冲突：SpringBoot 2.6 + 用 Knife4j 3.x 版本，避免路径匹配问题。

2. 生产环境不想暴露文档？
在生产环境关闭接口文档，避免接口泄露：

在application-prod.yml（生产配置）中加开关：

knife4j:
  enable: false  # 生产环境关闭Knife4j

配置类中读取开关：

@Bean(value = "defaultApi2")
public Docket defaultApi2(@Value("${knife4j.enable:true}") boolean enable) {
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(enable) // 根据开关决定是否开启
            .apiInfo(buildApiInfo())
            .groupName("1.0版本")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.heima"))
            .paths(PathSelectors.any())
            .build();
}

3. 注解不生效？

确保注解导对包：Knife4j 的@EnableKnife4j是com.github.xiaoymin.knife4j.annotations包下的，别导错；
POJO 类的@ApiModelProperty要加在属性上，且接口参数要用@RequestBody（否则不显示实体属性）。

四、Swagger vs Knife4j 怎么选？一张表搞定

维度	Swagger（默认版）	Knife4j（增强版）
UI 界面	简陋，排版乱	美观，支持排序、搜索
核心功能	自动生成文档、在线调试	包含 Swagger 所有功能，加离线文档、参数过滤等
依赖数量	需要 2 个依赖（核心 + UI）	1 个依赖搞定
学习成本	低	低（兼容 Swagger 注解，不用重新学）
适用场景	个人项目、简单接口	团队协作、企业级项目（需要规范文档）