api-doc-generator

API Documentation Auto-Generator

Task Objectives

• This Skill is used to: automatically extract API information from project code and generate complete API documentation
• Capabilities include: code scanning, route identification, module division, documentation structuring, content filling
• Trigger conditions: the user requests "generate API documentation", "analyze project API", "write interface documentation", etc.

Prerequisites

Dependency Description

This Skill uses only the Python standard library (ast, re, json, pathlib, etc.) and requires no additional dependency installation.

Non-standard File/Folder Preparation

No prior creation is required; the output directory will be created automatically when the documentation is generated.

Operation Steps

Standard Process

1. Step 1: Scan Project API

   • Call scripts/api_scanner.py to scan the project code
   • Parameters:
     • --project-dir: project root directory (required)
     • --framework: framework type (auto/flask/fastapi/express, default auto)
     • --output: output JSON file path (default api_scan_result.json)
   • Output: a JSON file containing information on all API endpoints

2. Step 2: Module Division and Hierarchy Analysis

   • Call scripts/module_classifier.py to analyze the API structure
   • Parameters:
     • --input: the JSON file path output in the previous step
     • --output: output JSON file path (default api_modules.json)
   • Output: an API list with module grouping and hierarchy information

3. Step 3: Generate Documentation Structure

   • Create the api/ folder in the project root directory
   • According to references/doc-structure.md create the documentation framework based on the specifications in:
     • api/overview.md - API Overview
     • api/authentication.md - Authentication Methods
     • api/base-info.md - Basic Information
     • api/endpoints/ - Endpoint Details (organized by module)
     • api/error-handling.md - Error Handling
     • api/rate-limiting.md - Rate Limiting
     • api/changelog.md - Changelog
     • api/support.md - Support and Feedback

4. Step 4: Fill in Documentation Content

   • Based on the module division results, create independent endpoint documentation for each module
   • Use assets/templates/ to fill in the content using the templates in
   • Supplement explanatory text, example code, notes, etc.

Optional Branches

• When the project uses the Flask framework: explicitly specify --framework flask in Step 1 to improve recognition accuracy
• When the project uses the FastAPI framework: explicitly specify --framework fastapi in Step 1 to leverage type annotation information
• When the project uses the Express framework: explicitly specify --framework express in Step 1 to identify JavaScript routes
• When custom module grouping is needed: after Step 2, manually adjust the module grouping logic before generating the documentation

Resource Index

Required Scripts

• See scripts/api_scanner.py
  • Purpose: scan project code and extract API route and parameter information
  • Parameters: --project-dir, --framework, --output
• See scripts/module_classifier.py
  • Purpose: Automatically divide modules and hierarchy structure based on route paths
  • Parameters: --input, --output

Domain Reference

• See references/doc-structure.md
  • When to read: Refer to this when generating the document structure in step 3
  • Content: Standard chapter structure and format specifications for API documentation
• See references/framework-patterns.md
  • When to read: Understand how the script identifies route definitions of different frameworks
  • Content: Route definition patterns and identification rules for various Web frameworks

Output Assets

• See assets/templates/
  • Purpose: Provide document templates for each chapter and endpoint
  • Includes: overview-template.md, endpoint-template.md, module-template.md

Notes

• The script uses regular expressions and AST parsing to identify routes. For complex dynamic routes, it may not be able to fully identify them, and manual supplementation is required
• Parameter extraction depends on code comments and type annotations. It is recommended to improve docstrings in the code
• Module division is based on the first segment of the path. For special structures, manual adjustment may be required
• After generating the documentation, it is recommended to manually review and supplement business descriptions, usage examples, etc.
• Only read reference documents when needed to keep the context concise

Usage Examples

Example 1: Flask project documentation generation

# 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. 智能体根据模板生成完整文档

Example 2: FastAPI project documentation generation

# 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

Example 3: Express project documentation generation

# 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