egg-jianghu-api-doc

egg-jianghu-api-doc

江湖 API 文档生成插件 - 企业级 API 文档自动化解决方案

🚀 核心特性

• 🔄 增量生成: 智能检测资源变更，只生成必要的文档部分
• 🔍 高级搜索: 全文搜索引擎，支持多条件过滤和搜索建议
• 🔐 Token 管理: 安全的 Token 存储和管理，支持多环境配置
• 🌍 环境管理: 多环境配置支持，环境间 Token 同步
• 📄 多格式导出: 支持 JSON、Markdown、PDF、HTML 格式导出
• ⚠️ 错误处理: 统一的错误处理机制，详细的错误分类和编码
• 📝 结构化日志: 多级别日志管理，日志查询和导出功能
• 💾 智能缓存: 多层缓存架构，提升文档生成性能

📦 安装

npm i egg-jianghu-api-doc --save

🔧 使用

1. 启用插件

// {app_root}/config/plugin.js
exports.jianghuApiDoc = {
  enable: true,
  package: 'egg-jianghu-api-doc',
};

2. 基础配置

// {app_root}/config/config.default.js
exports.jianghuApiDoc = {
  appName: '我的应用',
  version: '1.0.0',
  baseUrl: 'http://localhost:7001',
  autoGenerate: true,
  cache: {
    enabled: true,
    ttl: 3600000 // 1小时
  },
  logging: {
    level: 'INFO',
    retentionDays: 30
  }
};

🎯 快速开始

访问文档

启动应用后，访问以下地址：

• API 文档: /{appId}/jianghu-api-doc
• 管理界面: /{appId}/jianghu-api-doc/manage
• Swagger UI: /{appId}/public/apidoc/index.html

生成文档

# 访问生成接口
GET /{appId}/jianghu-api-doc/generate

# 强制重新生成
GET /{appId}/jianghu-api-doc/generate?force=true

📚 功能演示

运行综合演示脚本：

node demos/demo-comprehensive.js

运行单个功能演示：

# 增量生成演示
node demos/demo-incremental.js

# 搜索功能演示
node demos/demo-search.js

# Token 管理演示
node demos/demo-token-management.js

# 导出功能演示
node demos/demo-export-functionality.js

# 错误处理和日志演示
node demos/demo-error-handling-logging.js

更多演示说明请查看 demos/README.md

🔧 API 接口

文档生成

• GET /{appId}/jianghu-api-doc/generate - 生成文档
• POST /{appId}/jianghu-api-doc/regenerate - 强制重新生成
• GET /{appId}/jianghu-api-doc/incremental/stats - 获取增量生成统计

搜索功能

• POST /{appId}/jianghu-api-doc/search - 搜索 API 文档
• GET /{appId}/jianghu-api-doc/search/suggestions - 获取搜索建议
• GET /{appId}/jianghu-api-doc/search/history - 获取搜索历史

Token 管理

• POST /{appId}/jianghu-api-doc/tokens - 添加 Token
• GET /{appId}/jianghu-api-doc/tokens - 获取 Token 列表
• PUT /{appId}/jianghu-api-doc/tokens/:id - 更新 Token
• DELETE /{appId}/jianghu-api-doc/tokens/:id - 删除 Token

环境管理

• POST /{appId}/jianghu-api-doc/environments - 添加环境
• GET /{appId}/jianghu-api-doc/environments - 获取环境列表
• POST /{appId}/jianghu-api-doc/environments/:name/test - 测试环境连接

导出功能

• POST /{appId}/jianghu-api-doc/export - 导出文档
• POST /{appId}/jianghu-api-doc/export/batch - 批量导出
• GET /{appId}/jianghu-api-doc/export/history - 获取导出历史

系统管理

• GET /{appId}/jianghu-api-doc/status - 获取系统状态
• GET /{appId}/jianghu-api-doc/cache/stats - 获取缓存统计
• DELETE /{appId}/jianghu-api-doc/cache - 清理缓存

🏗️ 架构设计

┌─────────────────────────────────────────────────────────────┐
│                    江湖 API 文档插件                          │
├─────────────────────────────────────────────────────────────┤
│  Controller Layer (路由和请求处理)                            │
├─────────────────────────────────────────────────────────────┤
│  Service Layer (业务逻辑)                                    │
│  ├── IncrementalGenerator (增量生成器)                        │
│  ├── CacheManager (缓存管理器)                               │
│  ├── SearchEngine (搜索引擎)                                 │
│  ├── TokenManager (Token管理器)                             │
│  ├── EnvironmentManager (环境管理器)                         │
│  ├── ExportManager (导出管理器)                              │
│  ├── ErrorHandler (错误处理器)                               │
│  └── LogManager (日志管理器)                                 │
├─────────────────────────────────────────────────────────────┤
│  Storage Layer (存储层)                                      │
│  ├── File System (文件系统)                                  │
│  ├── Memory Cache (内存缓存)                                 │
│  └── Encrypted Storage (加密存储)                            │
└─────────────────────────────────────────────────────────────┘

🔒 安全特性

• Token 加密存储: 使用 AES-256-GCM 加密算法
• 环境隔离: 不同环境的 Token 完全隔离
• 访问控制: 支持基于角色的访问控制
• 审计日志: 完整的操作审计日志

📈 性能优化

• 增量生成: 只生成变更的文档部分，大幅提升性能
• 多层缓存: 内存 + 文件双重缓存机制
• 智能索引: 高效的搜索索引构建
• 异步处理: 非阻塞的文档生成和导出

🛠️ 开发指南

项目结构

egg-jianghu-api-doc/
├── app/
│   ├── controller/jianghuApiDoc.js     # 控制器
│   ├── service/jianghuApiDoc.js        # 主服务
│   ├── service/jianghuApiDoc/          # 子模块
│   └── router.js                       # 路由配置
├── config/
│   └── config.default.js               # 默认配置
├── docs/                               # 项目文档
│   ├── README.md                       # 文档目录
│   ├── FAQ.md                          # 常见问题
│   ├── OPTIMIZATION_COMPLETE.md        # 项目总结
│   └── *SUMMARY.md                     # 功能说明文档
├── demos/                              # 功能演示脚本
│   ├── README.md                       # 演示说明
│   ├── demo-comprehensive.js           # 综合演示
│   └── demo-*.js                       # 单功能演示
├── example/                            # 示例应用
├── openspec/                           # OpenSpec 变更提案
└── README.md                           # 项目说明

扩展开发

• 添加新的导出格式:

  // 在 ExportManager 中添加新的格式处理器
  async exportCustomFormat(swaggerSpec, options) {
    // 实现自定义格式导出逻辑
  }
  

• 自定义错误类型:

  // 在 ErrorHandler 中添加新的错误类型
  this.errorTypes.CUSTOM_ERROR = 'CUSTOM_ERROR';
  

• 扩展搜索功能:

  // 在 SearchEngine 中添加自定义搜索逻辑
  async customSearch(query, options) {
    // 实现自定义搜索逻辑
  }
  

🤝 贡献指南

• Fork 项目
• 创建功能分支 (git checkout -b feature/AmazingFeature)
• 提交更改 (git commit -m 'Add some AmazingFeature')
• 推送到分支 (git push origin feature/AmazingFeature)
• 打开 Pull Request

📄 许可证

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

🆘 支持

如果您遇到问题或有建议，请：

• 查看 常见问题
• 阅读 项目文档
• 运行 功能演示
• 提交 Issue 或参与讨论

📊 更新日志

v1.0.0 (2024-12-14)

• ✨ 全新的模块化架构设计
• 🚀 增量文档生成机制
• 🔍 高级搜索功能
• 🔐 安全的 Token 管理系统
• 🌍 多环境配置支持
• 📄 多格式文档导出
• ⚠️ 统一错误处理机制
• 📝 结构化日志系统
• 💾 智能缓存管理

江湖 API 文档插件 - 让 API 文档生成更简单、更高效、更安全！