一、概述

Knife4j 是一款基于 Swagger 的開源 API 文檔工具，旨在為 Java 開發者提供更美觀、功能更強大的 API 文檔生成、展示和調試體驗。它是 Swagger-Bootstrap-UI 的升級版，通過增強 UI 界面和擴展功能，解決了原生 Swagger UI 界面簡陋、功能有限的問題。

二、核心功能

1. 美觀的 UI 界面
   Knife4j 提供了更加美觀、直觀的界面，提升了開發者的使用體驗。

2. 自動生成文檔
   通過集成 Swagger，Knife4j 可以自動從代碼中解析 API 注解，生成規范的 API 文檔。

3. 接口分組
   支持根據業務需求將接口進行分組，方便用戶對接口進行組織和查看。

4. 參數設置
   支持多種參數類型的展示和設置，包括基本類型、對象、集合等。

5. 請求示例與調試
   提供接口請求示例，并支持在線調試接口，方便開發者進行測試。

6. 響應模型配置
   提供全局統一的響應模型配置，方便用戶對接口返回數據進行管理和定義。

7. 離線文檔導出
   支持將 API 文檔導出為離線的 HTML、PDF 或 Markdown 文件，方便分享。

8. 多環境支持
   支持在不同的環境（如開發、測試、生產等）中使用不同的 API 文檔配置。

9. Markdown 支持
   在 API 文檔中使用 Markdown 語法，使文檔更具可讀性和易于維護。

三、使用步驟

1. 添加依賴
   在項目的 pom.xml 文件中添加 Knife4j 的依賴。例如：

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

2. 配置 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
   

3. 使用注解
   在 Controller 類或方法上使用 Knife4j 提供的注解來生成 API 文檔。例如：

   @RestController
   @RequestMapping("/api")
   @Tag(name = "示例API")
   public class IndexController {@Operation(summary = "用戶登錄")public Result<LoginVo> login(@RequestBody LoginDto loginDto) {// 業務邏輯}
   }
   

4. 訪問 API 文檔
   啟動項目后，訪問 http://localhost:8080/doc.html 即可查看生成的 API 文檔。

四、優點

1. 界面友好
   Knife4j 提供了更加美觀、易用的 UI 界面，提升了開發者的體驗感。

2. 功能強大
   支持接口分組、參數設置、請求示例、響應模型配置等高級功能。

3. 易于集成
   提供了 Spring Boot Starter，可以實現更加便捷的集成。

4. 擴展性強
   提供了多種插件擴展，如 knife4j-auth、knife4j-rate-limiter 等，可以滿足不同項目的需求。

五、適用場景

• 微服務架構
  在微服務架構中，Knife4j 可以幫助開發者快速生成和管理各個服務的 API 文檔。

• 前后端分離開發
  在前后端分離的開發模式下，Knife4j 可以為前端開發者提供清晰的 API 文檔和調試接口。

• 需要美觀 UI 的項目
  如果項目對 API 文檔的 UI 界面有較高要求，Knife4j 是一個不錯的選擇。

六、離線導出功能詳解

Knife4j 的離線文檔導出功能是其核心特性之一，允許開發者將生成的 API 文檔導出為多種格式的靜態文件（如 HTML、Markdown、PDF），便于在無網絡環境或非開發場景下共享和查閱。以下從功能特點、使用方法、應用場景及注意事項等方面詳細介紹。

---

一、功能特點

1. 多格式支持

   • HTML：導出為完整的靜態網頁，保留所有交互功能（如接口調試、參數折疊等）。
   • Markdown：導出為純文本文件，適合集成到文檔工具（如 GitBook、Confluence）或版本控制中。
   • PDF：生成可打印的文檔，適合正式交付或存檔（需配合工具如 Pandoc 或瀏覽器打印功能）。

2. 保留核心功能

   • 導出后的文檔仍包含接口分組、請求示例、響應模型、參數說明等關鍵信息。
   • HTML 格式支持在線調試（需部署到靜態服務器）。

3. 自定義配置

   • 可配置導出的標題、描述、版本號等元數據。
   • 支持選擇性導出（如僅導出特定分組或接口）。

4. 一鍵操作

   • 通過 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）自定義導出邏輯（需參考官方文檔或源碼）。

---

三、應用場景

1. 團隊協作

   • 將導出的 HTML 或 Markdown 文檔共享給非技術團隊（如產品、測試），無需訪問開發環境。

2. 交付客戶

   • 提供 PDF 格式的文檔作為項目交付物，滿足合規或存檔需求。

3. 版本管理

   • 將 Markdown 文檔納入 Git 倉庫，與代碼版本同步更新。

4. 無網絡環境

   • 在內網或離線環境中使用導出的 HTML 文檔進行接口調試。

---

四、注意事項

1. PDF 導出限制

   • Knife4j 本身不直接生成 PDF，需通過以下方式實現：
     • 瀏覽器打印：在 HTML 文檔中按 Ctrl+P 保存為 PDF。
     • 第三方工具：使用 Pandoc 將 Markdown 轉換為 PDF。

2. 敏感信息過濾

   • 導出前檢查文檔中是否包含敏感信息（如接口密鑰、內部路徑），可通過注解（如 @ApiIgnore）或配置排除。

3. 靜態資源依賴

   • 導出的 HTML 文檔依賴靜態資源（如 CSS、JS），需確保完整下載或部署到服務器。

4. 版本兼容性

   • 不同版本的 Knife4j 可能對導出格式的支持有差異，建議查閱對應版本的官方文檔。

---

五、對比其他工具

功能	Knife4j	Swagger UI	Postman 導出
導出格式	HTML/Markdown/PDF（需工具）	僅 JSON/YAML	HTML/Markdown/PDF
交互性	HTML 保留調試功能	僅查看	僅查看
配置復雜度	低（UI 一鍵操作）	中（需代碼或插件）	中（需 Postman 賬號）
適用場景	開發/交付/協作	開發調試	測試/交付

---

六、總結

Knife4j 的離線文檔導出功能通過簡潔的 UI 和靈活的配置，解決了 API 文檔共享和存檔的痛點。其優勢在于：

1. 多格式支持，滿足不同場景需求；
2. 保留核心功能，確保離線文檔的可用性；
3. 低學習成本，開發者無需額外學習即可上手。

建議：

• 對于需要頻繁共享文檔的團隊，優先使用 HTML 格式。
• 對于正式交付，結合 Markdown 和 PDF 工具生成規范文檔。
• 定期檢查導出文檔的完整性，避免遺漏關鍵信息。

---