Claude-Code-Workflow/.claude/skills/software-manual/scripts/api-extractor.md

API 文档提取脚本

根据项目类型自动提取 API 文档，支持 FastAPI、Next.js、Python 模块。

支持的技术栈

类型	技术栈	工具	输出格式
Backend	FastAPI	openapi-to-md	Markdown
Frontend	Next.js/TypeScript	TypeDoc	Markdown
Python Module	Python	pdoc	Markdown/HTML

使用方法

1. FastAPI Backend (OpenAPI)

# 提取 OpenAPI JSON
cd D:/dongdiankaifa9/backend
python -c "
from app.main import app
import json
print(json.dumps(app.openapi(), indent=2))
" > api-docs/openapi.json

# 转换为 Markdown (使用 widdershins)
npx widdershins api-docs/openapi.json -o api-docs/API_REFERENCE.md --language_tabs 'python:Python' 'javascript:JavaScript' 'bash:cURL'

备选方案 (无需启动服务):

# scripts/extract_fastapi_openapi.py
import sys
sys.path.insert(0, 'D:/dongdiankaifa9/backend')

from app.main import app
import json

openapi_schema = app.openapi()
with open('api-docs/openapi.json', 'w', encoding='utf-8') as f:
    json.dump(openapi_schema, f, indent=2, ensure_ascii=False)

print(f"Extracted {len(openapi_schema.get('paths', {}))} endpoints")

2. Next.js Frontend (TypeDoc)

cd D:/dongdiankaifa9/frontend

# 安装 TypeDoc
npm install --save-dev typedoc typedoc-plugin-markdown

# 生成文档
npx typedoc --plugin typedoc-plugin-markdown \
  --out api-docs \
  --entryPoints "./lib" "./hooks" "./components" \
  --entryPointStrategy expand \
  --exclude "**/node_modules/**" \
  --exclude "**/*.test.*" \
  --readme none

typedoc.json 配置:

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./lib", "./hooks", "./components"],
  "entryPointStrategy": "expand",
  "out": "api-docs",
  "plugin": ["typedoc-plugin-markdown"],
  "exclude": ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
  "excludePrivate": true,
  "excludeInternal": true,
  "readme": "none",
  "name": "Frontend API Reference"
}

3. Python Module (pdoc)

# 安装 pdoc
pip install pdoc

# hydro_generator_module
cd D:/dongdiankaifa9
pdoc hydro_generator_module \
  --output-dir api-docs/hydro_generator \
  --format markdown \
  --no-show-source

# multiphysics_network
pdoc multiphysics_network \
  --output-dir api-docs/multiphysics \
  --format markdown \
  --no-show-source

备选: Sphinx (更强大):

# 安装 Sphinx
pip install sphinx sphinx-markdown-builder

# 生成 API 文档
sphinx-apidoc -o docs/source hydro_generator_module
cd docs && make markdown

集成脚本

#!/usr/bin/env python3
# scripts/extract_all_apis.py

import subprocess
import sys
from pathlib import Path

PROJECTS = {
    'backend': {
        'path': 'D:/dongdiankaifa9/backend',
        'type': 'fastapi',
        'output': 'api-docs/backend'
    },
    'frontend': {
        'path': 'D:/dongdiankaifa9/frontend',
        'type': 'typescript',
        'output': 'api-docs/frontend'
    },
    'hydro_generator_module': {
        'path': 'D:/dongdiankaifa9/hydro_generator_module',
        'type': 'python',
        'output': 'api-docs/hydro_generator'
    },
    'multiphysics_network': {
        'path': 'D:/dongdiankaifa9/multiphysics_network',
        'type': 'python',
        'output': 'api-docs/multiphysics'
    }
}

def extract_fastapi(config):
    """提取 FastAPI OpenAPI 文档"""
    path = Path(config['path'])
    sys.path.insert(0, str(path))
    
    try:
        from app.main import app
        import json
        
        output_dir = Path(config['output'])
        output_dir.mkdir(parents=True, exist_ok=True)
        
        # 导出 OpenAPI JSON
        with open(output_dir / 'openapi.json', 'w', encoding='utf-8') as f:
            json.dump(app.openapi(), f, indent=2, ensure_ascii=False)
        
        print(f"✓ FastAPI: {len(app.openapi().get('paths', {}))} endpoints")
        return True
    except Exception as e:
        print(f"✗ FastAPI error: {e}")
        return False

def extract_typescript(config):
    """提取 TypeScript 文档"""
    try:
        subprocess.run([
            'npx', 'typedoc',
            '--plugin', 'typedoc-plugin-markdown',
            '--out', config['output'],
            '--entryPoints', './lib', './hooks',
            '--entryPointStrategy', 'expand'
        ], cwd=config['path'], check=True)
        print(f"✓ TypeDoc: {config['path']}")
        return True
    except Exception as e:
        print(f"✗ TypeDoc error: {e}")
        return False

def extract_python(config):
    """提取 Python 模块文档"""
    try:
        module_name = Path(config['path']).name
        subprocess.run([
            'pdoc', module_name,
            '--output-dir', config['output'],
            '--format', 'markdown'
        ], cwd=Path(config['path']).parent, check=True)
        print(f"✓ pdoc: {module_name}")
        return True
    except Exception as e:
        print(f"✗ pdoc error: {e}")
        return False

EXTRACTORS = {
    'fastapi': extract_fastapi,
    'typescript': extract_typescript,
    'python': extract_python
}

if __name__ == '__main__':
    for name, config in PROJECTS.items():
        print(f"\n[{name}]")
        extractor = EXTRACTORS.get(config['type'])
        if extractor:
            extractor(config)

Phase 3 集成

在 api-reference Agent 提示词中添加：

[PRE-EXTRACTION]
运行 API 提取脚本获取结构化文档：
- python scripts/extract_all_apis.py

[INPUT FILES]
- api-docs/backend/openapi.json (FastAPI endpoints)
- api-docs/frontend/*.md (TypeDoc output)
- api-docs/hydro_generator/*.md (pdoc output)
- api-docs/multiphysics/*.md (pdoc output)

输出结构

api-docs/
├── backend/
│   ├── openapi.json          # Raw OpenAPI spec
│   └── API_REFERENCE.md      # Converted Markdown
├── frontend/
│   ├── modules.md
│   ├── functions.md
│   └── classes/
├── hydro_generator/
│   ├── assembler.md
│   ├── blueprint.md
│   └── builders/
└── multiphysics/
    ├── analysis_domain.md
    ├── builders.md
    └── compilers.md