# Phase 2.5: API Extraction

在项目探索后、并行分析前，自动提取 API 文档。

## 核心原则

**使用成熟工具提取，确保输出格式与 wiki 模板兼容。**

## 执行流程

```javascript
const config = JSON.parse(Read(`${workDir}/manual-config.json`));

// 检查项目路径配置
const apiSources = config.api_sources || detectApiSources(config.project_path);

// 执行 API 提取
Bash({
  command: `python .claude/skills/software-manual/scripts/extract_apis.py -o "${workDir}" -p ${apiSources.join(' ')}`
});

// 验证输出
const apiDocsDir = `${workDir}/api-docs`;
const extractedFiles = Glob(`${apiDocsDir}/**/*.{json,md}`);
console.log(`Extracted ${extractedFiles.length} API documentation files`);
```

## 支持的项目类型

| 类型 | 检测方式 | 提取工具 | 输出格式 |
|------|----------|----------|----------|
| FastAPI | `app/main.py` + FastAPI import | OpenAPI JSON | `openapi.json` + `API_SUMMARY.md` |
| Next.js | `package.json` + next | TypeDoc | `*.md` (Markdown) |
| Python Module | `__init__.py` + setup.py/pyproject.toml | pdoc | `*.md` (Markdown) |
| Express | `package.json` + express | swagger-jsdoc | `openapi.json` |
| NestJS | `package.json` + @nestjs | @nestjs/swagger | `openapi.json` |

## 输出格式规范

### Markdown 兼容性要求

确保输出 Markdown 与 wiki CSS 样式兼容：

```markdown
# API Reference                    → <h1> (wiki-base.css)

## Endpoints                       → <h2>

| Method | Path | Summary |        → <table> 蓝色表头
|--------|------|---------|
| `GET`  | `/api/...` | ...   |    → <code> 红色高亮

### GET /api/users                 → <h3>

\`\`\`json                          → <pre><code> 深色背景
{
  "id": 1,
  "name": "example"
}
\`\`\`

- Parameter: `id` (required)       → <ul><li> + <code>
```

### 格式验证检查

```javascript
function validateApiDocsFormat(apiDocsDir) {
  const issues = [];
  const mdFiles = Glob(`${apiDocsDir}/**/*.md`);
  
  for (const file of mdFiles) {
    const content = Read(file);
    
    // 检查表格格式
    if (content.includes('|') && !content.match(/\|.*\|.*\|/)) {
      issues.push(`${file}: 表格格式不完整`);
    }
    
    // 检查代码块语言标注
    const codeBlocks = content.match(/```(\w*)\n/g) || [];
    const unlabeled = codeBlocks.filter(b => b === '```\n');
    if (unlabeled.length > 0) {
      issues.push(`${file}: ${unlabeled.length} 个代码块缺少语言标注`);
    }
    
    // 检查标题层级
    if (!content.match(/^# /m)) {
      issues.push(`${file}: 缺少一级标题`);
    }
  }
  
  return issues;
}
```

## 项目配置示例

在 `manual-config.json` 中配置 API 源：

```json
{
  "software": {
    "name": "Hydro Generator Workbench",
    "type": "web"
  },
  "api_sources": {
    "backend": {
      "path": "D:/dongdiankaifa9/backend",
      "type": "fastapi",
      "entry": "app.main:app"
    },
    "frontend": {
      "path": "D:/dongdiankaifa9/frontend",
      "type": "typescript",
      "entries": ["lib", "hooks", "components"]
    },
    "hydro_generator_module": {
      "path": "D:/dongdiankaifa9/hydro_generator_module",
      "type": "python"
    },
    "multiphysics_network": {
      "path": "D:/dongdiankaifa9/multiphysics_network",
      "type": "python"
    }
  }
}
```

## 输出结构

```
{workDir}/api-docs/
├── backend/
│   ├── openapi.json          # OpenAPI 3.0 规范
│   └── API_SUMMARY.md        # Markdown 摘要（wiki 兼容）
├── frontend/
│   ├── modules.md            # TypeDoc 模块文档
│   ├── classes/              # 类文档
│   └── functions/            # 函数文档
├── hydro_generator/
│   ├── assembler.md          # pdoc 模块文档
│   ├── blueprint.md
│   └── builders/
└── multiphysics/
    ├── analysis_domain.md
    ├── builders.md
    └── compilers.md
```

## 质量门禁

- [ ] 所有配置的 API 源已提取
- [ ] Markdown 格式与 wiki CSS 兼容
- [ ] 表格正确渲染（蓝色表头）
- [ ] 代码块有语言标注
- [ ] 无空文件或错误文件

## 下一阶段

→ [Phase 3: Parallel Analysis](03-parallel-analysis.md)