API 文档自动生成器

任务目标

• 本 Skill 用于：从项目代码中自动提取API信息并生成完整的API文档
• 能力包含：代码扫描、路由识别、模块划分、文档结构化、内容填充
• 触发条件：用户要求”生成API文档”、”分析项目API”、”编写接口文档”等

前置准备

依赖说明

本 Skill 仅使用 Python 标准库（ast, re, json, pathlib等），无需额外安装依赖。

非标准文件/文件夹准备

无需前置创建，输出目录将在文档生成时自动创建。

操作步骤

标准流程

1. 步骤1：扫描项目API

   • 调用 scripts/api_scanner.py 扫描项目代码
   • 参数：
     • --project-dir: 项目根目录（必需）
     • --framework: 框架类型（auto/flask/fastapi/express，默认auto）
     • --output: 输出JSON文件路径（默认api_scan_result.json）
   • 输出：包含所有API端点信息的JSON文件

2. 步骤2：模块划分与层级分析

   • 调用 scripts/module_classifier.py 分析API结构
   • 参数：
     • --input: 上一步输出的JSON文件路径
     • --output: 输出JSON文件路径（默认api_modules.json）
   • 输出：带模块分组和层级信息的API清单

3. 步骤3：生成文档结构

   • 在项目根目录下创建 api/ 文件夹
   • 根据 references/doc-structure.md 中的规范创建文档框架：
     • api/overview.md – API概述
     • api/authentication.md – 认证方式
     • api/base-info.md – 基础信息
     • api/endpoints/ – 端点详情（按模块组织）
     • api/error-handling.md – 错误处理
     • api/rate-limiting.md – 速率限制
     • api/changelog.md – 变更日志
     • api/support.md – 支持与反馈

4. 步骤4：填充文档内容

   • 根据模块划分结果，为每个模块创建独立的端点文档
   • 使用 assets/templates/ 中的模板填充内容
   • 补充说明文字、示例代码、注意事项等

可选分支

• 当项目使用Flask框架：在步骤1中明确指定 --framework flask 以提高识别准确率
• 当项目使用FastAPI框架：在步骤1中明确指定 --framework fastapi 以利用类型注解信息
• 当项目使用Express框架：在步骤1中明确指定 --framework express 以识别JavaScript路由
• 当需要自定义模块分组：在步骤2后，手动调整模块分组逻辑再生成文档

资源索引

必要脚本

• 见 scripts/api_scanner.py
  • 用途：扫描项目代码，提取API路由和参数信息
  • 参数：–project-dir, –framework, –output
• 见 scripts/module_classifier.py
  • 用途：基于路由路径自动划分模块和层级结构
  • 参数：–input, –output

领域参考

• 见 references/doc-structure.md
  • 何时读取：在步骤3生成文档结构时参考
  • 内容：API文档的标准章节结构和格式规范
• 见 references/framework-patterns.md
  • 何时读取：理解脚本如何识别不同框架的路由定义
  • 内容：各Web框架的路由定义模式和识别规则

输出资产

• 见 assets/templates/
  • 用途：提供各章节和端点的文档模板
  • 包含：overview-template.md, endpoint-template.md, module-template.md

注意事项

• 脚本使用正则表达式和AST解析识别路由，对于复杂的动态路由可能无法完全识别，需要手动补充
• 参数提取依赖于代码注释和类型注解，建议在代码中完善文档字符串
• 模块划分基于路径的第一段，对于特殊结构可能需要手动调整
• 生成文档后，建议人工审核并补充业务说明、使用示例等
• 仅在需要时读取参考文档，保持上下文简洁

使用示例

示例1：Flask项目文档生成

# 1. 扫描Flask项目
python scripts/api_scanner.py \
  --project-dir /path/to/flask/project \
  --framework flask \
  --output api_scan_result.json

# 2. 划分模块
python scripts/module_classifier.py \
  --input api_scan_result.json \
  --output api_modules.json

# 3-4. 智能体根据模板生成完整文档

示例2：FastAPI项目文档生成

# FastAPI项目会自动识别类型注解和Pydantic模型
python scripts/api_scanner.py \
  --project-dir /path/to/fastapi/project \
  --framework fastapi

python scripts/module_classifier.py \
  --input api_scan_result.json

示例3：Express项目文档生成

# Node.js Express项目
python scripts/api_scanner.py \
  --project-dir /path/to/express/project \
  --framework express

python scripts/module_classifier.py \
  --input api_scan_result.json