Claude-Code-Workflow/.claude/skills/software-manual/phases/02.5-api-extraction.md

Phase 2.5: API Extraction

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

核心原则

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

执行流程

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 样式兼容：

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

格式验证检查

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 源：

{
  "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