当前位置：首页 > news >正文

Knife4j 使用详解

news 2025/7/14 20:37:36

一、概述

Knife4j 是一款基于 Swagger 的开源 API 文档工具，旨在为 Java 开发者提供更美观、功能更强大的 API 文档生成、展示和调试体验。它是 Swagger-Bootstrap-UI 的升级版，通过增强 UI 界面和扩展功能，解决了原生 Swagger UI 界面简陋、功能有限的问题。

二、核心功能

美观的 UI 界面
Knife4j 提供了更加美观、直观的界面，提升了开发者的使用体验。
自动生成文档
通过集成 Swagger，Knife4j 可以自动从代码中解析 API 注解，生成规范的 API 文档。
接口分组
支持根据业务需求将接口进行分组，方便用户对接口进行组织和查看。
参数设置
支持多种参数类型的展示和设置，包括基本类型、对象、集合等。
请求示例与调试
提供接口请求示例，并支持在线调试接口，方便开发者进行测试。
响应模型配置
提供全局统一的响应模型配置，方便用户对接口返回数据进行管理和定义。
离线文档导出
支持将 API 文档导出为离线的 HTML、PDF 或 Markdown 文件，方便分享。
多环境支持
支持在不同的环境（如开发、测试、生产等）中使用不同的 API 文档配置。
Markdown 支持
在 API 文档中使用 Markdown 语法，使文档更具可读性和易于维护。

三、使用步骤

添加依赖
在项目的 pom.xml 文件中添加 Knife4j 的依赖。例如：

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

配置 Knife4j
可以通过创建配置类或修改 application.yml 文件来配置 Knife4j。例如：

@Configuration
public class Knife4jConfig {@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("admin-api").pathsToMatch("/admin/**").build();}@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("接口文档").version("1.0").description("接口文档").contact(new Contact().name("zuozhe")));}
}

或在 application.yml 中配置：

knife4j:enable: trueopenapi:title: API文档的标题description: API文档的详细描述version: 1.0.0

使用注解
在 Controller 类或方法上使用 Knife4j 提供的注解来生成 API 文档。例如：

@RestController
@RequestMapping("/api")
@Tag(name = "示例API")
public class IndexController {@Operation(summary = "用户登录")public Result<LoginVo> login(@RequestBody LoginDto loginDto) {// 业务逻辑}
}

访问 API 文档
启动项目后，访问 http://localhost:8080/doc.html 即可查看生成的 API 文档。

四、优点

界面友好
Knife4j 提供了更加美观、易用的 UI 界面，提升了开发者的体验感。
功能强大
支持接口分组、参数设置、请求示例、响应模型配置等高级功能。
易于集成
提供了 Spring Boot Starter，可以实现更加便捷的集成。
扩展性强
提供了多种插件扩展，如 knife4j-auth、knife4j-rate-limiter 等，可以满足不同项目的需求。

五、适用场景

微服务架构
在微服务架构中，Knife4j 可以帮助开发者快速生成和管理各个服务的 API 文档。
前后端分离开发
在前后端分离的开发模式下，Knife4j 可以为前端开发者提供清晰的 API 文档和调试接口。
需要美观 UI 的项目
如果项目对 API 文档的 UI 界面有较高要求，Knife4j 是一个不错的选择。

六、离线导出功能详解

Knife4j 的离线文档导出功能是其核心特性之一，允许开发者将生成的 API 文档导出为多种格式的静态文件（如 HTML、Markdown、PDF），便于在无网络环境或非开发场景下共享和查阅。以下从功能特点、使用方法、应用场景及注意事项等方面详细介绍。

一、功能特点

多格式支持
- HTML：导出为完整的静态网页，保留所有交互功能（如接口调试、参数折叠等）。
- Markdown：导出为纯文本文件，适合集成到文档工具（如 GitBook、Confluence）或版本控制中。
- PDF：生成可打印的文档，适合正式交付或存档（需配合工具如 Pandoc 或浏览器打印功能）。
保留核心功能
- 导出后的文档仍包含接口分组、请求示例、响应模型、参数说明等关键信息。
- HTML 格式支持在线调试（需部署到静态服务器）。
自定义配置
- 可配置导出的标题、描述、版本号等元数据。
- 支持选择性导出（如仅导出特定分组或接口）。
一键操作
- 通过 UI 界面或代码配置即可快速导出，无需复杂操作。

二、使用方法

1. 通过 UI 界面导出

步骤：
1. 启动项目并访问 Knife4j 的文档界面（如 http://localhost:8080/doc.html）。
2. 在页面右上角找到 “导出” 按钮（通常为下载图标）。
3. 选择导出格式（HTML/Markdown/PDF）。
4. 确认后下载生成的离线文档。

2. 通过代码配置导出

Spring Boot 项目配置：
在 application.yml 中启用导出功能并配置参数：

knife4j:enable: trueproduction: true  # 启用生产模式（隐藏调试功能）openapi:title: "API 文档"description: "离线导出示例"version: "1.0"

动态导出（高级）：
通过 Knife4j 提供的 API 或插件（如 knife4j-export）自定义导出逻辑（需参考官方文档或源码）。

三、应用场景

团队协作
- 将导出的 HTML 或 Markdown 文档共享给非技术团队（如产品、测试），无需访问开发环境。
交付客户
- 提供 PDF 格式的文档作为项目交付物，满足合规或存档需求。
版本管理
- 将 Markdown 文档纳入 Git 仓库，与代码版本同步更新。
无网络环境
- 在内网或离线环境中使用导出的 HTML 文档进行接口调试。

四、注意事项

PDF 导出限制
- Knife4j 本身不直接生成 PDF，需通过以下方式实现：
  - 浏览器打印：在 HTML 文档中按 Ctrl+P 保存为 PDF。
  - 第三方工具：使用 Pandoc 将 Markdown 转换为 PDF。
敏感信息过滤
- 导出前检查文档中是否包含敏感信息（如接口密钥、内部路径），可通过注解（如 @ApiIgnore）或配置排除。
静态资源依赖
- 导出的 HTML 文档依赖静态资源（如 CSS、JS），需确保完整下载或部署到服务器。
版本兼容性
- 不同版本的 Knife4j 可能对导出格式的支持有差异，建议查阅对应版本的官方文档。

五、对比其他工具

功能	Knife4j	Swagger UI	Postman 导出
导出格式	HTML/Markdown/PDF（需工具）	仅 JSON/YAML	HTML/Markdown/PDF
交互性	HTML 保留调试功能	仅查看	仅查看
配置复杂度	低（UI 一键操作）	中（需代码或插件）	中（需 Postman 账号）
适用场景	开发/交付/协作	开发调试	测试/交付