egg-jianghu-api-doc
v2.0.1
Published
江湖 API 文档插件 - 企业级 API 文档自动化解决方案
Maintainers
yuanmengReadme
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- 添加 TokenGET /{appId}/jianghu-api-doc/tokens- 获取 Token 列表PUT /{appId}/jianghu-api-doc/tokens/:id- 更新 TokenDELETE /{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 文件了解详情。
🆘 支持
如果您遇到问题或有建议，请：
📊 更新日志
v1.0.0 (2024-12-14)
- ✨ 全新的模块化架构设计
- 🚀 增量文档生成机制
- 🔍 高级搜索功能
- 🔐 安全的 Token 管理系统
- 🌍 多环境配置支持
- 📄 多格式文档导出
- ⚠️ 统一错误处理机制
- 📝 结构化日志系统
- 💾 智能缓存管理
江湖 API 文档插件 - 让 API 文档生成更简单、更高效、更安全！