SpringBoot 整合 Knife4j 生成接口文档实战

前言

前后端分离模式下，接口文档的质量直接决定联调效率。很多团队初期使用 Word、Postman 文档、在线表格记录接口，一旦代码改动，文档经常遗忘更新，出现“文档一套、代码一套”的情况。

Swagger 可以通过注解扫描代码自动生成接口描述，而 Knife4j 是 Swagger 的增强 UI，界面更清爽，支持离线文档导出、接口排序、全局参数、请求缓存等实用功能，国内很多 SpringBoot 项目都在使用。本文从零搭建演示项目，带你快速接入。

一、环境依赖

SpringBoot 版本选择 2.7.x（Knife4j 对 SpringBoot3 需要额外适配，这里选用兼容性更好的版本）
Maven 依赖：

<!-- knife4j 启动器 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

注意：SpringBoot3 需要用 knife4j-openapi3-jakarta-spring-boot-starter，包名不一样，不要混用。

二、Knife4j 配置类

新建配置类 Knife4jConfig.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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 分组名称
                .groupName("v1版本接口")
                .select()
                // 扫描Controller包路径，改成你自己的controller包
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后端接口文档")
                .description("基于Knife4j自动生成的接口文档，支持在线调试")
                .termsOfServiceUrl("[https://www.huaweicloud.com](https://www.huaweicloud.com)")
                .contact(new Contact("demo", "", ""))
                .version("1.0")
                .build();
    }
}

三、编写测试Controller，使用注解

常用注解说明：

• @Api：标记Controller模块名称
• @ApiOperation：接口名称、描述
• @ApiParam：入参说明
• @ApiModel、@ApiModelProperty：实体类注释

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Api(tags = "用户模块")
public class UserController {

    @GetMapping("/info")
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID查询基础信息")
    public String getUserInfo(
            @ApiParam(value = "用户id", required = true)
            @RequestParam Long userId
    ) {
        return "用户ID：" + userId + "，用户名称：测试用户";
    }
}

四、访问文档地址

启动项目后，访问地址：

[http://localhost:8080/doc.html](http://localhost:8080/doc.html)

打开页面就可以看到 Knife4j 界面，左侧展示所有分组和接口，点开接口可以直接填写参数、发送请求调试，不用借助 Postman。

五、生产环境关闭接口文档

接口文档不能暴露在公网生产环境，存在信息泄露风险。推荐两种方案：

1. 通过配置文件开关控制

knife4j:
  enable: true
  production: false

把 production 设置为 true 即可关闭文档访问。

2. 多环境配置：dev环境开启，prod环境关闭，借助SpringBoot的 @Profile("dev") 把配置类只在开发环境加载。

六、常见坑点总结

1. 404打不开 doc.html：检查依赖版本和SpringBoot版本匹配，SpringBoot2和3包不能混用；
2. 接口扫描不到：确认 basePackage 路径写对，Controller 必须加 @RestController；
3. 配置了跨域、拦截器，把Knife4j静态资源拦截：需要放行 /doc.html、/webjars/**、/v2/api-docs；
4. 注解不生效：不要混用 OpenAPI3 和 Swagger2 的注解。

七、扩展能力

Knife4j 还支持很多实用功能：

• 导出 Markdown、Word、PDF 离线接口文档；
• 设置全局请求头（比如统一携带token）；
• 多分组管理，按业务模块拆分接口；
• 接口排序、忽略指定接口。

结语

Knife4j 接入成本很低，只需要少量配置和注解，就能做到代码和文档同步维护，减少大量沟通成本。在内部管理系统、中小型后端项目里非常合适。但一定要记住生产环境禁用，避免接口信息被外部人员浏览和探测。