Appearance
apidoc
简介
apidoc 是一个从源代码中的注释自动生成 API 文档的工具，特别适用于 JavaScript 项目。它支持多种编程语言，并生成美观的 HTML 文档。
安装
bash
npm install apidoc -g基本使用
1. 配置 apidoc.json
在项目根目录创建 apidoc.json 文件：
json
{
"name": "示例 API",
"version": "1.0.0",
"description": "API 文档示例",
"title": "自定义 API 文档",
"url": "https://api.example.com"
}2. 编写 API 注释
在源代码中添加符合 apidoc 格式的注释：
javascript
/**
* @api {get} /users/:id 获取用户信息
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id 用户ID
*
* @apiSuccess {String} name 用户名称
* @apiSuccess {String} email 用户邮箱
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "name": "John Doe",
* "email": "john@example.com"
* }
*/
app.get('/users/:id', function (req, res) {
// 处理逻辑
})3. 生成文档
bash
apidoc -i src/ -o docs/高级特性
1. 分组和版本控制
javascript
/**
* @apiDefine admin 管理员访问权限
* 只有管理员才能访问该接口
*/
/**
* @api {post} /users 创建用户
* @apiVersion 1.1.0
* @apiGroup User
* @apiPermission admin
*/2. 参数验证
javascript
/**
* @api {post} /users 创建用户
* @apiParam {String{1..64}} username 用户名
* @apiParam {String{6..20}} password 密码
* @apiParam {String="active","inactive"} status 状态
*/3. 错误处理
javascript
/**
* @apiError UserNotFound 用户未找到
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/最佳实践
保持注释结构一致
- 使用统一的注释格式
- 保持参数描述清晰
合理使用分组
- 按功能模块分组
- 使用适当的版本控制
完善的错误文档
- 记录所有可能的错误情况
- 提供清晰的错误示例
定期更新文档
- 代码更新时同步更新文档
- 保持示例代码的有效性
注意事项
- 注释必须以
/**开始 - 每个注释块必须包含
@api声明 - 参数描述要清晰准确
- 定期清理过时的 API 文档