API 文档生成指南
本项目的 API 文档采用手动维护的方式。
📝 工作流程
1. 维护 OpenAPI 文档
在 docs/api-specs/ 目录中维护 OpenAPI 文档。
目录结构
docs/api-specs/
├── user/ # 用户模块
│ ├── login.md
│ ├── login_status.md
│ └── ...
├── favorite/ # 收藏模块
│ ├── add.md
│ ├── del.md
│ └── list.md
└── ...
文档格式
每个 .md 文件包含：
- 接口描述（Markdown 格式）
- OpenAPI 3.0.1 规范（YAML 格式）
示例（docs/api-specs/user/login.md）：
```markdown
登录并绑定 OpenID
接口信息
- 方法: POST
- 路径: /srv/?a=user&t=login
- 标签: user
OpenAPI 规范
```yaml openapi: 3.0.0 info: title: 登录并绑定 OpenID description: 使用手机号和验证码登录，并绑定到 OpenID version: 1.0.0 paths: /srv/?: post: summary: 登录并绑定 OpenID description: 使用手机号和验证码登录，并绑定到 OpenID requestBody: content: application/x-www-form-urlencoded: schema: type: object required: - f - a - t properties: f: type: string description: 业务模块标识 example: manulife a: type: string description: 模块名（user） example: user t: type: string description: 接口类型（login） example: login phone: type: string description: 手机号 example: '13800138000' code: type: string description: 验证码 example: '123456' openid: type: string description: 微信 OpenID example: 'oXXXX-XXXXXXXXXXXXXXXXXXX' responses: '200': description: 成功 content: application/json: schema: type: object properties: code: type: number description: 状态码（0=失败，1=成功） msg: type: string description: 消息 data: type: object description: 用户信息 properties: id: type: number description: 用户 ID avatar: type: string description: 头像 URL name: type: string description: 姓名 ``` ```
2. 生成 API 代码
运行生成脚本：
node scripts/generateApiFromOpenAPI.js
生成内容
脚本会：
- 扫描
docs/api-specs/目录 - 解析每个
.md文件中的 OpenAPI 规范 - 生成对应的 JavaScript API 文件到
src/api/目录
输出示例
``` === OpenAPI 转 API 文档生成器 ===
输入目录: /Users/huyirui/program/itomix/git/manulife-weapp/docs/api-specs 输出目录: /Users/huyirui/program/itomix/git/manulife-weapp/src/api
💾 备份当前 OpenAPI 文档...
找到 9 个模块: event, favorite, feedback, file, get_file_list, get_product, news, user, wechat
处理模块: user 找到 5 个 API 文档 ✓ get_profile: 获取个人信息 ✓ login: 登录并绑定openid ✓ login_status: 查询登录状态 ✓ logout: 退出登录并解绑openid ✓ update_profile: 更新个人资料 📝 生成文件: /Users/huyirui/program/itomix/git/manulife-weapp/src/api/user.js
✅ API 文档生成完成！ ```
3. 使用生成的 API
在组件中导入并使用：
```javascript import { loginAPI, getUserProfileAPI } from '@/api/user';
// 登录 const result = await loginAPI({ phone: '13800138000', code: '123456', openid: 'oXXXX-XXXXXXXXXXXXXXXXXXX' });
if (result.code === 1) { console.log('登录成功', result.data); } ```
🔧 高级功能
API 变更检测
脚本会自动检测 API 变更：
- ✅ 新增接口 - 检测到新的 API 文档
- ⚠️ 修改接口 - 检测到 API 规范变更
- ❌ 删除接口 - 检测到删除的 API 文档
变更报告示例
``` 🔍 开始检测 API 变更...
📦 新增模块: user 包含 2 个新增接口: • POST /srv/?a=user&t=login - 登录并绑定 OpenID • GET /srv/?a=user&t=get_profile - 获取个人信息
📦 对比范围: 9 个旧接口 → 11 个新接口 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 新增接口 (2):
- login - 登录并绑定 OpenID
- get_profile - 获取个人信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 总计: 2 新增, 0 修改, 0 删除 ✅ 未检测到破坏性变更 ```
📚 最佳实践
1. 文档命名
- 使用语义化文件名（如
login.md,get_list.md） - 避免使用通用名称（如
api.md,endpoint.md）
2. 参数定义
-
必填参数：在
required数组中列出 -
可选参数：不在
required中 -
描述：为每个参数添加清晰的
description -
示例：为每个参数添加
example
3. 响应结构
- 统一使用
{ code, msg, data }格式 -
code: 状态码（0=失败，1=成功） -
msg: 消息说明 -
data: 数据内容
4. 文档分组
- 按业务模块分组（user, favorite, product 等）
- 每个模块一个目录
- 相关接口放在同一目录
🛠️ 故障排除
问题：YAML 解析失败
错误信息： ``` ✗ login.md: 解析失败 - YAML 代码块格式错误 ```
解决方案：
- 检查 YAML 代码块是否正确包裹在
\``yaml和```` 之间 - 检查 YAML 缩进是否正确（使用空格，不要使用 Tab）
- 使用在线 YAML 验证器验证格式
问题：未找到 YAML 代码块
错误信息： ``` ⚠️ login.md: 未找到 YAML 代码块 ```
解决方案：
- 确保文档中包含
\``yaml` 代码块 - 检查代码块格式是否正确
问题：生成的 API 代码为空
可能原因：
- OpenAPI 文档格式不正确
-
paths或requestBody定义缺失
解决方案：
- 检查 OpenAPI 文档结构是否完整
- 参考本文档中的示例格式