SpringBoot2.7集成Knife4j

Spring Boot 2.7 集成 Swagger 接口文档完整指南（knife4j + OpenAPI3）

1-knife4j和swagger关系->Knife4j 是 Swagger 生态的增强 UI 前端

2-SpringBoot集成knife4j->【添加依赖】+【配置knife4j开发】+【配置SwaggerConfig】

    <!-- knife4j：基于 OpenAPI3(springdoc) 的增强 Swagger UI，文档地址 /doc.html -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
        <version>4.4.0</version>
    </dependency>

3-地址访问：

• knife4j 增强文档（推荐）：http://localhost:8076/doc.html
• wagger 官方 UI：http://localhost:8076/swagger-ui/index.html

4-代码仓库：https://gitee.com/enzoism/springboot-knife-2.7.18

• knife4j 增强文档（推荐）：http://localhost:8076/doc.html

  

• Swagger 官方 UI：http://localhost:8076/swagger-ui/index.html

  

---

1-集成knife4j + OpenAPI3

一、最终效果

启动项目后，浏览器访问：

• knife4j 增强文档（推荐）：http://localhost:8076/doc.html
• OpenAPI3 原始 JSON：http://localhost:8076/v3/api-docs
• Swagger 官方 UI：http://localhost:8076/swagger-ui/index.html

在文档页面中可以直接看到接口分组（@Tag）、接口说明（@Operation）、出入参结构（实体自动解析），并支持在线调试。

---

二、验证环境一览

本工程实测通过的版本组合如下（mvn dependency:tree 实际输出）：

组件	版本	说明
JDK	1.8	pom.xml 中 <java.version>1.8</java.version>
Spring Boot	2.7.18	2.x 的最后一个正式版本，兼容 JDK 8
knife4j	4.4.0	knife4j-openapi3-spring-boot-starter，增强版 Swagger UI
springdoc-openapi	1.7.0	knife4j 传递引入，OpenAPI3 规范的 Spring 实现
swagger-annotations	2.2.9	knife4j 传递引入，io.swagger.v3.oas.annotations.* 注解包来源
swagger-ui	4.18.2	knife4j 传递引入的官方 UI（备用）
构建工具	Maven	Spring Boot 官方 parent 管理版本

依赖关系一句话总结：

knife4j-openapi3-spring-boot-starter:4.4.0
 ├─ knife4j-core / knife4j-openapi3-ui          （knife4j 增强文档 /doc.html）
 └─ springdoc-openapi-ui:1.7.0
     ├─ springdoc-openapi-common / webmvc-core  （扫描 Controller 生成 OpenAPI3 JSON）
     │   └─ swagger-core / swagger-annotations:2.2.9 （@Tag/@Operation/@Schema 等注解）
     └─ swagger-ui:4.18.2                       （官方 UI /swagger-ui/index.html）

只需要官方 UI、不需要 knife4j 增强功能的话，直接引入 org.springdoc:springdoc-openapi-ui:1.7.0 也可以，注解用法完全相同。

---

三、版本选型说明（重要）

3.1 Spring Boot 2.x 和 3.x 用不同的 starter

knife4j 4.x 针对不同 Spring Boot 大版本提供了两个 starter，不能混用：

Spring Boot 版本	应使用的依赖	底层	包名空间
2.x（本工程 2.7.18）	knife4j-openapi3-spring-boot-starter	springdoc-openapi 1.x	javax.*
3.x	knife4j-openapi3-jakarta-spring-boot-starter	springdoc-openapi 2.x	jakarta.*

Spring Boot 3 从 javax.* 换成了 jakarta.*，所以老 starter 在 Spring Boot 3 下无法工作；反之亦然。先确定 Spring Boot 大版本，再选 starter。

3.2 OpenAPI3 注解 vs 旧版 Swagger2 注解

网上大量旧教程使用 springfox 的 @Api / @ApiOperation（Swagger2 规范），springfox 已停止维护且与新版 JDK 不兼容。本工程采用 OpenAPI3 规范（springdoc） ，注解全部来自 io.swagger.v3.oas.annotations 包。新旧注解对照：

旧版 Swagger2（springfox，不推荐）	新版 OpenAPI3（本工程使用）	用途
@Api(tags = "...")	@Tag(name = "...", description = "...")	标注 Controller，生成分组
@ApiOperation("...")	@Operation(summary = "...", description = "...")	标注接口方法
@ApiModel	@Schema（标在实体类上）	标注出入参实体
@ApiModelProperty("...")	@Schema（标在实体字段上）	标注字段含义
@ApiParam	@Parameter	标注单个参数
@ApiImplicitParams	@Parameters	标注多个参数
@ApiResponses / @ApiResponse	@ApiResponses / @ApiResponse（包不同）	标注响应码说明

---

四、快速开始（三步接入）

步骤 1：添加 Maven 依赖

pom.xml 关键内容（Spring Boot 版本由 parent 统一管理，knife4j 需显式指定版本）：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
    <relativePath/>
</parent>

<properties>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <!-- Web 能力 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- knife4j：基于 OpenAPI3(springdoc) 的增强 Swagger UI，文档地址 /doc.html -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
        <version>4.4.0</version>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

无需额外引入 springdoc 或 swagger-annotations，knife4j starter 已全部传递引入。

步骤 2：编写配置文件

src/main/resources/application.yaml：

server:
  port: 8076

knife4j:
  # 开启 knife4j 增强模式（doc.html 的高级功能）
  enable: true

knife4j.enable: true 开启增强模式后，/doc.html 可使用全局参数、接口排序、缓存等高级功能；不开也能正常看文档。

步骤 3：声明全局文档信息

新建 SwaggerConfig，通过 OpenAPI Bean 配置文档标题、描述、版本等元信息：

package com.enzoism.springboot.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * knife4j(Swagger) 文档配置
 * 启动后访问 http://localhost:8076/doc.html 查看并调试接口
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(new Info()
                .title("接口文档标题")          // 文档页顶部标题，按项目自定义
                .description("接口文档描述信息") // 文档页说明文字，按项目自定义
                .version("1.0.0"));
    }
}

到这里接入就完成了，不加任何注解文档也能生成 （springdoc 会自动扫描所有 @RestController），注解只是让文档更易读。启动验证：

mvn spring-boot:run
# 或者 IDE 直接运行启动类

启动类就是普通的 Spring Boot 写法，没有任何特殊之处：

@SpringBootApplication
public class UsrApplication {
    public static void main(String[] args) {
        SpringApplication.run(UsrApplication.class, args);
    }
}

---

五、如何添加 Swagger 标注信息（注解实战）

OpenAPI3 的注解按作用层级分为四类，本工程已实际使用前两类：

层级	注解	作用
Controller 类	@Tag	定义文档中的接口分组名称与描述
接口方法	@Operation	定义接口的概要说明与详细描述
实体类/字段	@Schema	定义出入参模型的字段含义、示例值
方法参数	@Parameter	定义单个请求参数的说明

5.1 @Tag + @Operation：Controller 层标注（本工程实际代码）

package com.enzoism.springboot.controller;

import com.enzoism.springboot.common.AjaxResult;
import com.enzoism.springboot.model.UserModel;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Slf4j
@Tag(name = "用户快速调试", description = "验证Swagger")   // 类级：文档左侧的接口分组
@RestController
@RequestMapping("/usr")
public class UserController {

    @Operation(summary = "查询用户列表", description = "快速验证User用户列表查询") // 方法级：接口条目的名称与说明
    @GetMapping("/list")
    public AjaxResult send() {
        List<UserModel> userModels = UserModel.initUserModels();
        return AjaxResult.success(userModels);
    }
}

两个注解的核心属性：

• @Tag.name：分组名称（必填）；description：分组补充描述。
• @Operation.summary：接口一句话概要，显示为接口条目名称；description：点开后的详细说明。

5.2 @Schema：实体层标注（推荐补充）

出入参实体默认只展示字段名和类型，加上 @Schema 后会显示字段中文含义和示例值，文档可读性大幅提升。以本工程的 UserModel 为例，标注后的写法：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户实体")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserModel {

    @Schema(description = "用户ID", example = "1")
    private Integer id;

    @Schema(description = "年龄", example = "18")
    private Integer age;

    @Schema(description = "用户名", example = "zhangsan")
    private String name;

    public static List<UserModel> initUserModels() {
        return Arrays.asList(
                new UserModel(1, 18, "zhangsan"),
                new UserModel(2, 19, "lisi"),
                new UserModel(3, 20, "wangwu")
        );
    }
}

统一响应体同样建议标注，例如给 AjaxResult 的 code / msg / data 字段加上 @Schema(description = "状态码") 等，响应示例会更清晰。

5.3 @Parameter：参数级标注

GET 查询参数、路径参数的说明用 @Parameter：

@Operation(summary = "按ID查询用户")
@GetMapping("/{id}")
public AjaxResult getById(
        @Parameter(description = "用户ID", required = true, example = "1")
        @PathVariable Integer id) {
    return AjaxResult.success();
}

POST 请求体的字段说明则回到 @Schema，由框架自动把实体字段文档挂到接口的 Request Body 下。

---

六、启动与调试流程

1. 启动应用（IDE 运行 UsrApplication，或 mvn spring-boot:run）。
2. 打开 http://localhost:8076/doc.html 。
3. 左侧按 @Tag 分组浏览接口，接口条目名称来自 @Operation.summary。
4. 点击接口 → 「调试」Tab → 「发送」，即可在页面内直接发起请求并查看响应（端口为 application.yaml 中配置的 8076）。

---

七、常见问题（FAQ）

1. 访问 /doc.html 返回 404？

• 确认引入的是 knife4j-openapi3-spring-boot-starter（缺 knife4j 时只有 /swagger-ui/index.html，没有 /doc.html）；
• 确认 application.yaml 中 knife4j.enable: true；
• 确认项目有拦截器/安全框架放行了 /doc.html、/v3/api-docs、/swagger-ui/**、/webjars/**。

2. 文档 JSON 地址是什么？

/v3/api-docs，返回 OpenAPI3 规范的 JSON，可导入 Apifox、Postman 等工具。

3. 生产环境如何关闭文档？

在对应环境的配置中关闭 springdoc 即可：

springdoc:
  api-docs:
    enabled: false

（关闭后 /doc.html 无数据可加载，如需彻底隐藏可再配合拦截器屏蔽相关路径。）

4. Spring Boot 3 项目能直接用本工程的依赖吗？

不能。Spring Boot 3 需换成 knife4j-openapi3-jakarta-spring-boot-starter（内置 springdoc 2.x），注解写法不变。

5. 项目里已经有 springfox（@EnableSwagger2）会冲突吗？

会。springfox 与 springdoc 扫描机制冲突，二选一。建议迁移到本工程的 OpenAPI3 方案，按第三章的对照表替换注解即可。

---

八、工程结构速览

20261030SpringBoot-Swagger
├── pom.xml                                            # Spring Boot 2.7.18 + knife4j 4.4.0
└── src/main
    ├── java/com/enzoism/springboot
    │   ├── UsrApplication.java                        # 启动类
    │   ├── config/SwaggerConfig.java                  # OpenAPI Bean：文档元信息
    │   ├── controller/UserController.java             # @Tag + @Operation 标注示例
    │   ├── model/UserModel.java                       # 出入参实体
    │   └── common/AjaxResult.java                     # 统一响应体
    └── resources/application.yaml                     # 端口 + knife4j 增强

九、总结

• 版本组合 ：JDK 1.8 + Spring Boot 2.7.18 + knife4j-openapi3-spring-boot-starter 4.4.0（内置 springdoc 1.7.0），这是一套经过本工程实际运行验证的稳定组合。
• 接入成本 ：一个依赖、两行配置、一个 OpenAPI Bean，三步完成，不加注解也有完整文档。
• 注解体系 ：类上 @Tag、方法上 @Operation、实体和字段上 @Schema、参数上 @Parameter，全部来自 io.swagger.v3.oas.annotations 包。
• 版本红线：Spring Boot 2.x 与 3.x 的 starter 不能混用；不要与 springfox 混存于同一项目。

---

2-Knife4j和Swagger之间是什么关系

两者关系：Knife4j 是 Swagger 生态的增强 UI 前端

简单来说：Swagger 提供 API 文档的标准和生成能力，Knife4j 是在其之上的增强版文档展示界面。Knife4j 本身不生成 API 文档数据，它消费 Swagger/OpenAPI 产出的规范数据，用更友好的界面渲染出来。

各自的角色

Swagger（现称 OpenAPI 生态）

• 是一套 API 文档规范（OpenAPI Specification）加上围绕它的工具链：Swagger UI、Swagger Editor、Codegen 等。
• 在 Java 中，通常通过 Springfox 或 SpringDoc 这类库扫描代码注解（如 @ApiOperation、@Operation），生成符合 OpenAPI 规范的 JSON 数据（/v2/api-docs 或 /v3/api-docs）。
• 自带的 Swagger UI 是纯英文界面，功能比较基础。

Knife4j

• 前身叫 swagger-bootstrap-ui，是一个中国开发者（萧明）主导的开源项目，2020 年更名为 Knife4j。
• 它是一个前端 UI 增强方案，底层仍然依赖 Springfox/SpringDoc 生成的 OpenAPI 数据，只是替换了展示层。
• 可以理解为给 Swagger 换了一个功能更强的"皮肤"，但又不只是皮肤。

Knife4j 相比原生 Swagger UI 的增强

• 中文界面，更符合国内团队习惯
• 接口调试功能更强（类似 Postman，支持参数缓存、全局参数、自定义请求头）
• 支持文档导出（Markdown、Word、PDF、HTML）
• 接口排序、分组、搜索、离线文档
• 支持多文档源聚合（微服务网关下聚合各服务的文档）
• 支持动态参数、增强的注解（如 @ApiOperationSupport、@ApiSupport 控制排序等）

典型集成方式

<!-- Spring Boot 项目中，Knife4j 会自动带上 Springfox 依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

引入后访问 /doc.html 就是 Knife4j 界面，而原生的 /swagger-ui.html 依然可用------这也说明两者是共存关系，Knife4j 只是替换了展示层。

一句话总结

Swagger/OpenAPI 是标准和数据生产者，Knife4j 是站在它之上的增强型文档 UI。没有 Swagger（Springfox/SpringDoc）生成的规范数据，Knife4j 无米下锅；有了 Knife4j，Swagger 文档在国内团队里变得好用得多。

---