| name | api-extractor-pro |
| description | 前端 API 治理工作站：从项目中的真实 API 调用扫描接口，生成结构化契约（contract.json）、MSW Mock、标准接口文档（Markdown + OpenAPI 3.1 YAML），并执行一致性校验与变更追踪。 |
API Extractor Pro
从前端代码出发，聚焦 扫描接口 → 生成契约 → 产出 Mock → 输出文档 → 校验一致性 → 追踪变更。
适用场景
- 前端项目已有 API 调用，但缺少接口文档
- 需要统一产出
contract.json / OpenAPI / MSW
- 需要 CI/CD 中自动化校验接口一致性
- 需要多次迭代间追踪接口变更
职责边界（强制）
本 skill 只做接口治理产物生成与校验：
- ✅ 做：扫描 API 调用、生成
contract.json、生成 Mock、生成文档、校验一致性、生成 diff 报告
- ❌ 不做：页面业务逻辑改造、静态页面数据迁移、页面状态流重构
页面 API 化改造应由 static-to-api-layer 在前置阶段完成。
前置条件（推荐）
若项目是静态页面起步，建议先执行：
static-to-api-layer：完成页面 API 化api-extractor-pro：统一生成治理产物
若项目本身已存在标准 API 调用，可直接使用本 skill。
七阶段工作流
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 1. Scan │───▶│2. Contract│───▶│ 3. Confirm│───▶│ 4. Mock │
│ 扫描分析 │ │ 生成契约 │ │ 用户确认 │ │ MSW生成 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│
┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ 7. Report│◀───│ 6. Verify│◀───│ 5. Docs │◀─────────┘
│ 变更报告 │ │ 一致性校验│ │ 文档生成 │
└──────────┘ └──────────┘ └──────────┘
阶段 1：扫描分析（Scan）
目标：收集项目中所有 API 调用
执行方式：
python3 scripts/scan.py --project-root <项目根目录> [--scope src/pages,src/views] [--entry-hints src/api,src/services]
支持 Axios / Fetch / request 封装 / React Query / SWR 等模式。
输出：scan_result.json
阶段 2：生成契约（Contract）
目标：将扫描结果转化为结构化接口契约
执行方式：
python3 scripts/build_contract.py --scan-result scan_result.json --auth-mode bearer --output contract.json
contract.json 是整个工作流唯一事实源（SSOT）。
阶段 3：用户确认（Confirm）
目标：整理接口清单并确认推断项，确认后更新 contract.json。
阶段 4：生成 MSW Mock（Mock）
目标：从 contract.json 生成 MSW handlers 和 mock 数据。
执行方式：
python3 scripts/generate_msw.py --contract contract.json --output-root <项目根目录>
阶段 5：生成接口文档（Docs）
目标：从 contract.json 生成 docs/api-docs.md 和 docs/openapi.yaml。
执行方式：
python3 scripts/generate_docs.py --contract contract.json --output-root <项目根目录> --project-name "项目名称"
阶段 6：一致性校验（Verify）
目标：交叉校验 contract ↔ OpenAPI ↔ MSW handlers。
执行方式：
python3 scripts/check_consistency.py \
--contract contract.json \
--openapi docs/openapi.yaml \
--handlers mock/handlers/ \
--report reports/consistency-report.md \
[--strict-mode]
阶段 7：变更报告（Report）
目标：对比上次契约与当前契约，生成 reports/api-diff.md。
一键执行（全自动模式）
python3 scripts/run_workflow.py --config config.json
输出产物清单
| 产物 | 路径 | 说明 |
|---|
| 扫描结果 | scan_result.json | 原始 API 调用扫描数据 |
| 接口契约 | contract.json | 唯一事实源，结构化接口定义 |
| MSW Handler | mock/handlers/[module].js | 按模块分组的 Mock 拦截器 |
| MSW 数据 | mock/data/[module].json | 贴合业务的 Mock 数据 |
| MSW 入口 | mock/browser.js | Worker 启动入口 |
| 中文文档 | docs/api-docs.md | Markdown 格式接口文档 |
| OpenAPI | docs/openapi.yaml | OpenAPI 3.1 规范 |
| 一致性报告 | reports/consistency-report.md | 三方交叉校验结果 |
| 变更报告 | reports/api-diff.md | 接口变更追踪 |
强制规则
contract.json 是唯一事实源- 每个接口必须包含成功响应和至少一个错误响应
- 不确定字段统一标记为
x-todo-confirm
- 接口命名格式统一为
domain.action
- 本 skill 不修改业务逻辑页面代码
注意事项
- 若项目中有
api/ / services/ / request/，优先扫描这些目录
- URL 模板变量统一转为路径参数（如
/api/user/:id）
- 识别并输出
baseURL 与鉴权模式
- 分页、上传等模式需在文档中明确标注
- 微信小程序项目：MSW（Service Worker）在小程序中不可用，Mock 方案由
static-to-api-layer 的 mock-interceptor-wx.js 提供。本 skill 生成的 MSW Mock 仅适用于 Web 项目（React / Vue）
参考资料
- 契约结构规范：
references/contract-schema.md
- MSW 生成规范：
references/patterns-msw.md
- OpenAPI 生成规范：
references/patterns-openapi.md
- 文档模板：
templates/api-doc.md
- OpenAPI 模板：
templates/openapi.yaml
- Mock 示例：
examples/mock-handler-example.js
- 文档示例：
examples/api-docs-example.md
