API 文档生成工具

冲冲同学
77 阅读3分钟

API 文档预览和导出工具

Java Spring Boot Maven License

基于 Spring Boot 3 的 API 文档预览和导出工具，支持从 Swagger/Knife4J 文档 URL 获取接口信息，并提供 JSON、DOC、PDF 格式导出功能

✨ 特性

  • 🔍 自动检测：自动检测 Swagger/Knife4J 文档 URL（支持 v2、v3、swagger.json）
  • 📝 文档预览：美观的 Web 界面预览 API 文档，支持分组浏览和搜索
  • 📄 多格式导出：支持导出为 JSON、DOC（Word）、PDF 格式
  • 🎨 现代化 UI：采用现代化设计，界面美观易用，响应式布局适配多种屏幕
  • 🚀 开箱即用：无需复杂配置，启动即可使用
  • 🌐 跨域支持：支持从任何 Swagger/Knife4J 服务获取文档
  • 📊 详细文档：自动解析请求参数、响应参数、请求示例、响应示例
  • 🔄 Schema 解析：支持 $ref 引用解析，自动生成完整的参数说明和示例数据
  • 📋 统一响应格式：支持 R 统一响应格式解析

📦 技术栈

  • Spring Boot 3.3.0：核心框架
  • Java 17+：开发语言
  • WebFlux：响应式 HTTP 客户端（用于获取文档）
  • Apache POI：Word 文档生成
  • OpenHTMLToPDF：PDF 文档生成
  • Swagger Parser：OpenAPI/Swagger 文档解析
  • Jackson：JSON 处理

🚀 快速开始

环境要求

  • JDK 17 或更高版本
  • Maven 3.6 或更高版本

安装和运行

  1. 克隆项目
git clone https://gitee.com/your-username/api-doc-generator.git
cd api-doc-generator
  1. 编译项目
mvn clean package
  1. 运行应用
java -jar target/api-doc-generator-1.0.0.jar

或者使用 Maven 直接运行：

mvn spring-boot:run
  1. 访问应用

打开浏览器访问：http://localhost:8081（默认端口为 8081）

📖 使用说明

1. 预览 API 文档

  1. 启动应用后，访问 http://localhost:8081
  2. 在输入框中输入 Swagger/Knife4J 文档 URL，例如：
    • http://localhost:8080/v3/api-docs（OpenAPI 3.0）
    • http://localhost:8080/v2/api-docs（Swagger 2.0）
    • http://localhost:8080（自动检测）
  3. 点击"获取文档"按钮
  4. 系统会自动检测并获取 API 文档，并在页面上显示预览
  5. 左侧显示 API 分组（tags），右侧显示对应分组的接口列表
  6. 点击接口可展开查看详细信息，包括：
    • 基本信息（URL、请求方式、Content-Type）
    • 请求参数（Query、Header、Path 参数）
    • 请求 Body 参数（POST 请求）
    • 返回参数说明
    • 请求示例和响应示例（成功/失败）

2. 导出文档

预览文档后，可以点击右上角的导出按钮：

  • 📄 JSON：导出为 JSON 格式的 OpenAPI/Swagger 文档
  • 📝 DOC：导出为 Word 文档（.docx 格式），包含完整的接口文档，支持 Word 导航窗格
  • 📑 PDF：导出为 PDF 文档，包含完整的接口文档和样式

3. API 接口

应用也提供了 RESTful API 接口，可以直接调用：

获取文档数据
POST /api-doc/fetch
Content-Type: application/x-www-form-urlencoded

url=http://localhost:8080/v3/api-docs
导出 JSON
POST /api-doc/export/json
Content-Type: application/x-www-form-urlencoded

url=http://localhost:8080/v3/api-docs
导出 DOC
POST /api-doc/export/doc
Content-Type: application/x-www-form-urlencoded

url=http://localhost:8080/v3/api-docs
导出 PDF
POST /api-doc/export/pdf
Content-Type: application/x-www-form-urlencoded

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

🔧 配置说明

应用配置

编辑 src/main/resources/application.yml 可以修改配置：

server:
  port: 8081 # 服务端口

spring:
  application:
    name: api-doc-generator
  thymeleaf:
    check-template-location: false # 禁用 Thymeleaf 模板检查

api-doc:
  timeout: 30000 # 获取文档的超时时间（毫秒）
  allowed-domains: # 允许的域名白名单（为空则允许所有）
  cache-duration: 3600 # 缓存时间（秒）

PDF 中文字体配置

PDF 导出需要中文字体支持，请将字体文件放置在 src/main/resources/fonts/ 目录下：

  • 推荐使用 SimSun.ttc（宋体）
  • 字体文件会在应用启动时自动加载

📁 项目结构

api-doc-generator/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/gitee/apidoc/
│   │   │       ├── ApiDocGeneratorApplication.java      # 主启动类
│   │   │       ├── controller/                          # 控制器
│   │   │       │   ├── ApiDocController.java           # API文档控制器
│   │   │       │   └── IndexController.java             # 首页控制器
│   │   │       ├── service/                             # 服务层
│   │   │       │   ├── DocumentFetchService.java        # 文档获取服务
│   │   │       │   ├── DocumentParseService.java        # 文档解析服务
│   │   │       │   ├── ExportService.java                # 导出服务
│   │   │       │   ├── HtmlBasedExportService.java      # HTML 导出服务（PDF）
│   │   │       │   └── TemplateBasedWordExportService.java  # Word 导出服务
│   │   │       ├── model/                                # 数据模型
│   │   │       │   └── ApiDocInfo.java                   # API文档信息模型
│   │   │       └── config/                               # 配置类
│   │   │           └── TemplateInitializer.java         # Word 模板初始化
│   │   └── resources/
│   │       ├── application.yml                           # 应用配置
│   │       ├── static/
│   │       │   └── preview.html                          # 预览页面（静态 HTML）
│   │       ├── templates/
│   │       │   └── api-doc-template.docx                 # Word 导出模板
│   │       └── fonts/                                    # 字体文件目录
│   └── test/                                             # 测试代码
├── pom.xml                                               # Maven配置
└── README.md                                             # 项目说明

🎯 核心功能

1. 文档获取

  • 支持从 Swagger/Knife4J 服务获取文档
  • 自动检测文档版本（v2、v3、swagger.json）
  • 支持超时配置和错误处理
  • 使用 WebFlux 实现非阻塞 HTTP 请求

2. 文档解析

  • 解析 OpenAPI 3.0 和 Swagger 2.0 格式
  • 提取 API 基本信息、路径、参数等信息
  • 支持组件（schemas）解析和 $ref 引用解析
  • 自动生成请求示例和响应示例
  • 支持统一响应格式 R 解析

3. 文档导出

  • JSON 导出：保持原始 OpenAPI/Swagger 格式
  • DOC 导出：
    • 使用 Word 模板生成格式化的文档
    • 支持 Word 导航窗格（左侧标题栏）
    • 包含完整的接口信息、参数说明、示例数据
    • 支持多级标题（Heading1、Heading2、Heading3）
  • PDF 导出：
    • 基于 HTML 生成美观的 PDF 文档
    • 支持中文字体（需要配置字体文件）
    • 包含完整的接口信息和样式

4. 预览界面

  • 现代化 UI 设计，美观易用
  • 左侧分组导航，右侧内容展示
  • 支持分组搜索功能
  • 响应式布局，适配多种屏幕尺寸
  • 接口详情折叠展开，便于浏览

🔍 支持的文档格式

  • OpenAPI 3.0（/v3/api-docs）
  • Swagger 2.0（/v2/api-docs）
  • Swagger JSON（/swagger.json）

📝 示例

使用示例

  1. 假设你有一个运行在 http://localhost:8080 的 Spring Boot 应用，集成了 Swagger/Knife4J
  2. 启动本应用：mvn spring-boot:run
  3. 访问 http://localhost:8081
  4. 输入 http://localhost:8080/v3/api-docs
  5. 点击"获取文档"查看预览
  6. 点击"导出 PDF"或"导出 DOC"下载文档

Word 文档特性

导出的 Word 文档包含：

  • 封面页（自动填充标题、版本、日期等信息）
  • 接口分组（tags）作为一级标题，显示在 Word 导航窗格
  • 每个接口的详细信息：
    • 接口标题和描述
    • 请求 URL 和方式
    • 请求参数表格
    • 请求 Body 参数表格（POST 请求）
    • 返回参数表格
    • 请求示例和响应示例（成功/失败）

图片展示

image.png

image.png

🤝 贡献指南

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

👤 作者

wz

🙏 致谢

感谢所有为本项目做出贡献的开发者！

📮 反馈

如有问题或建议，请提交 Issue

⭐ 如果这个项目对你有帮助，请给它一个 Star！

avatar
文章
阅读
粉丝