Knife4j 入门笔记：接口文档工具介绍与 Spring Boot 接入方法

开发后端接口时，除了实现业务逻辑，还需要告诉前端和测试人员：接口地址是什么、需要哪些参数、会返回什么数据。

Knife4j 可以把这些信息整理成网页，并提供在线调试功能。这篇笔记记录它的用途，以及在 Spring Boot 项目中的基本接入方法。

一、Knife4j 是什么

Knife4j 是围绕 Swagger / OpenAPI 提供的接口文档增强工具，前身是 swagger-bootstrap-ui。它支持接口文档展示、在线调试、中文界面、接口排序、文档导出和多个服务的文档聚合。项目介绍、官方功能说明

可以将它理解为：

一份可以在浏览器中查看，并能直接发送请求的接口说明书。

例如，后端提供了一个查询用户的接口：

GET /users/123

在文档页面中，使用者可以看到接口用途、参数含义和返回结构，也可以填写参数发送请求，查看实际响应。

它主要帮助团队完成以下工作：

• 后端开发：维护接口说明。
• 前端开发：查看接口地址、参数和返回字段。
• 测试人员：发送请求，检查接口行为。

二、Knife4j 与 Swagger、OpenAPI 的关系

“Swagger 增强版”是对 Knife4j 的通俗描述。接入项目时，可以按下面的分工理解：

本文使用 OpenAPI 3 + springdoc-openapi 方案。Knife4j 对应的 Starter 会引入所需的 springdoc 依赖，因此应先检查项目已有依赖，避免重复引入不兼容的版本。Knife4j 接入说明

三、查看文档需要下载软件吗

只查看文档时，不需要安装桌面软件，浏览器即可访问。

如果项目已经接入 Knife4j，让后端提供文档地址即可。常见格式是：

http://服务器地址:端口/doc.html

本地项目的示例地址：

http://localhost:8080/doc.html

这里的 localhost 指当前电脑。如果服务部署在其他机器上，需要换成对应的服务器地址。

给自己的项目接入时，则需要修改后端依赖和配置，然后启动项目。

四、接入前先确认版本

本文以 Spring Boot 3、Spring MVC、Java 17、Maven 为例，使用官方快速开始中的 Knife4j 4.4.0 展示配置。这个版本是示例版本，实际项目应根据 Spring Boot 与 springdoc 的兼容关系选择依赖。

不同 Spring Boot 版本对应的 OpenAPI 3 Starter 如下：

尤其注意 Spring Boot 3 对应依赖中的 jakarta。这份示例不应直接套用到 Spring Boot 4 或 WebFlux 项目。官方版本参考

五、Spring Boot 3 接入步骤

1. 添加 Maven 依赖

假设项目已经包含 spring-boot-starter-web，在 pom.xml 的 <dependencies> 中添加：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

保存后，在 IDEA 中刷新 Maven，下载依赖。

2. 配置接口扫描范围

在 application.yml 中添加：

server:
  port: 8080

springdoc:
  group-configs:
    - group: default
      paths-to-match: '/**'
      packages-to-scan: com.example.demo.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

配置含义：

将 com.example.demo.controller 改成项目中真实的 Controller 包名。如果文件已有 server、springdoc 或 knife4j 节点，应合并配置。

上述依赖、分组配置和访问入口参考了官方快速开始。

3. 创建示例接口

在 com.example.demo.controller 包下创建 HelloController.java：

package com.example.demo.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "问候接口", description = "用于演示接口文档和在线调试")
public class HelloController {

    @GetMapping("/hello")
    @Operation(summary = "获取问候语")
    public String hello(
            @Parameter(description = "姓名", example = "小明")
            @RequestParam(name = "name", defaultValue = "World")
            String name) {
        return "Hello, " + name;
    }
}

这是一个简单的演示接口，请求：

GET /hello?name=小明

预期返回：

Hello, 小明

Controller 应放在 Spring Boot 启动类所在包的子包中，或通过组件扫描显式注册，否则接口本身也不会生效。

4. 启动项目并打开文档

启动 Spring Boot 应用，在浏览器访问：

http://localhost:8080/doc.html

如果配置了访问前缀：

server:
  servlet:
    context-path: /demo

则地址变为：

http://localhost:8080/demo/doc.html

在页面中找到“问候接口”，展开 /hello，进入调试区域，填写 name 并发送请求，即可检查返回结果。

这些是接入后的预期行为，实际结果需要在自己的项目中运行验证。

六、常用文档注解

OpenAPI 3 的注解通常位于 io.swagger.v3.oas.annotations 包下。

文档注解主要补充说明。参数是否必填、默认值是什么，以及字段是否合法，仍需要通过 Spring 参数绑定和校验机制实现。

如果是从旧 Swagger 2 项目迁移，应检查 @Api、@ApiOperation 等旧注解，避免直接与 OpenAPI 3 配置混用。springdoc 官方迁移说明

七、常见问题排查

1. 打开 doc.html 返回 404

可以依次检查：

• 应用是否启动成功，端口是否正确。
• 地址是否缺少 context-path 前缀。
• Knife4j 依赖是否下载成功、是否匹配项目版本。
• 项目是否修改了 Spring MVC 静态资源配置。

2. 页面能打开，但没有接口

先直接访问业务接口，例如：

http://localhost:8080/hello?name=小明

再检查 Controller 是否被 Spring 扫描，以及 packages-to-scan、paths-to-match 是否包含该接口。

还可以查看文档数据地址：

http://localhost:8080/v3/api-docs

本文配置了 default 分组，对应的分组文档地址通常为：

http://localhost:8080/v3/api-docs/default

如果数据接口返回错误，应先排查文档生成或访问权限，再检查页面展示。springdoc 官方文档

3. 页面或接口返回 401、403

项目的登录校验可能拦截了文档页面、静态资源或 /v3/api-docs/**。

需要分别处理两种权限：查看文档的权限，以及调试业务接口时的权限。业务接口要求登录令牌时，调试请求也需要携带对应凭证。

4. 启动时报依赖冲突

查看 Maven 依赖树：

mvn dependency:tree

重点检查 Knife4j、springdoc 和 Springfox 的版本。已有 Swagger 方案的项目，应先确定继续使用原方案还是迁移，再调整依赖。

其他版本相关问题可以查阅 Knife4j 官方 FAQ。

接入后，日常新增接口时补充用途、参数和模型说明，再通过文档页面检查生成结果，就能让接口文档随着代码一起维护。