# springboot-knife-2.7.18

**Repository Path**: enzoism/springboot-knife-2.7.18

## Basic Information

- **Project Name**: springboot-knife-2.7.18
- **Description**: springboot2.7.18使用Swagger的高阶版本：knife
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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



- knife4j 增强文档（推荐）：http://localhost:8076/doc.html
![](https://i-blog.csdnimg.cn/direct/095763050bc344cc8fd5a4bb19380502.png)


-  Swagger 官方 UI：http://localhost:8076/swagger-ui/index.html
![](https://i-blog.csdnimg.cn/direct/b0b4c4bad34645cd8c0dc7fba374bc4d.png)


---

# 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 需显式指定版本）：

```xml
<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`：

```yaml
server:
  port: 8076

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

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

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

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

```java
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`），注解只是让文档更易读。启动验证：

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

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

```java
@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 层标注（本工程实际代码）

```java
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` 为例，标注后的写法：

```java
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`：

```java
@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 即可：

```yaml
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` 控制排序等）

### 典型集成方式

```xml
<!-- 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 文档在国内团队里变得好用得多。

----