# 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)

```bash
# 提取 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'
```

**备选方案 (无需启动服务)**:
```python
# 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)

```bash
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 配置**:
```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)

```bash
# 安装 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 (更强大)**:
```bash
# 安装 Sphinx
pip install sphinx sphinx-markdown-builder

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

## 集成脚本

```python
#!/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
```