API Doc Generator

从代码注释自动生成漂亮的 API 文档网站。

特性

• 🚀 简单易用 - 零配置即可生成文档
• 🎨 主题系统 - 支持自定义主题
• 📱 响应式设计 - 完美适配移动端
• 🔍 搜索支持 - 快速查找 API
• 🔄 热重载 - 开发时自动刷新
• 🌐 一键部署 - 支持 GitHub Pages

安装

npm install -g @mazhu/apidoc-gen

快速开始

1. 初始化项目

apidoc-gen init

2. 编写 API 注释

/**
 * @api {get} /users 获取用户列表
 * @apiName GetUsers
 * @apiGroup User
 * @apiQuery {Number} [page=1] 页码
 * @apiQuery {Number} [limit=10] 每页数量
 * @apiSuccess {Object[]} users 用户列表
 * @apiSuccess {String} users.id 用户ID
 * @apiSuccess {String} users.name 用户名
 */

3. 生成文档

apidoc-gen build

4. 本地预览

apidoc-gen serve

5. 部署到 GitHub Pages

apidoc-gen deploy

支持的注释标签

| 标签 | 描述 | |------|------| | @api | 定义 API 方法和路径 | | @apiName | API 名称 | | @apiGroup | API 分组 | | @apiDescription | API 描述 | | @apiParam | 路径参数 | | @apiQuery | 查询参数 | | @apiBody | 请求体参数 | | @apiSuccess | 成功响应 | | @apiError | 错误响应 | | @apiHeader | 请求头 | | @apiExample | 示例代码 | | @apiVersion | API 版本 | | @apiPermission | 权限要求 | | @apiDeprecated | 已弃用标记 |

CLI 命令

# 初始化项目
apidoc-gen init

# 生成文档
apidoc-gen build
apidoc-gen build -c ./config.json

# 本地预览
apidoc-gen serve
apidoc-gen serve -p 8080
apidoc-gen serve -w  # 监视模式

# 部署到 GitHub Pages
apidoc-gen deploy

# 主题管理
apidoc-gen theme list
apidoc-gen theme create my-theme

配置文件

{
  "title": "My API Documentation",
  "description": "API documentation for my project",
  "version": "1.0.0",
  "srcDir": "./src",
  "outputDir": "./docs",
  "theme": "default",
  "baseUrl": "https://api.example.com",
  "include": ["**/*.js", "**/*.ts"],
  "exclude": ["node_modules/**", "test/**"]
}

自定义主题

# 创建新主题
apidoc-gen theme create my-theme

# 编辑主题文件
themes/my-theme/templates/
themes/my-theme/assets/

许可证

MIT

作者

Mike Wang [email protected]