用途
api-documentation 是一个用于强制保持 API 文档与代码同步的技能。当 API 代码发生变更（如路由、端点、Schema）时，它会检查 Swagger/OpenAPI 文档是否同步；一旦检测到文档漂移，就会暂停当前工作，直到文档同步完成。其核心原则是：API 文档是一等产物，而非事后补充，任何 API 变更都必须附带文档。
触发条件
当以下任意文件模式被修改时，该技能会被触发：
**/routes/**/*.ts（Express/Fastify 路由定义）**/controllers/**/*.ts（NestJS/Express 控制器端点）**/*.controller.ts（NestJS 控制器类）**/api/**/*.py（FastAPI/Flask API 端点）**/*_router.py（FastAPI 路由定义）**/handlers/**/*.go（Go HTTP 处理器）**/schema*.ts（TypeScript Schema 定义）**/dto/**/*.ts（NestJS 数据传输对象）**/models/**/*.ts（各类 API 模型）
主要能力
- 检测 API 变更：通过 git diff 检查常见 API 文件模式以及 schema/DTO 变更，判断当前改动是否影响 API。
- 查找文档文件：按顺序查找 openapi.yaml、openapi.json、swagger.yaml、swagger.json、docs/api.yaml、docs/openapi.yaml、api/openapi.yaml 等位置。若未找到文档文件，则报错并提示触发 documentation-audit 技能。
- 验证同步状态：从代码中提取端点，与 OpenAPI 文档中的路径进行比对，找出代码中存在但文档中缺失的端点。
- 处理文档漂移：若检测到漂移，输出暂停状态报告，列出缺失的端点及其代码位置，要求先调用 documentation-audit 技能、更新 Swagger/OpenAPI 文档，同步完成后再恢复工作。
使用方式
技能开始时需声明："I'm using api-documentation to verify Swagger/OpenAPI sync."
协议分为四步：
- 检测 API 变更（检查 routes/、controllers/、api/、handlers/、.controller.ts、_router.py 等模式，以及 schema/dto/model 变更）。
- 查找文档文件（遍历常见 OpenAPI/Swagger 文件路径）。
- 验证同步（对比代码端点与文档端点，使用 comm 找出缺失项）。
- 处理漂移（输出暂停报告，调用 documentation-audit 技能）。
文档更新要求包含以下字段：summary、description、parameters、requestBody、responses、tags、security。每个端点必须提供请求示例（POST/PUT/PATCH）、成功响应示例和错误响应示例。
更新后需验证文档，例如：
npx @apidevtools/swagger-cli validate openapi.yaml
或使用 yq 做基本结构检查：
yq 'has("openapi") and has("paths") and has("info")' openapi.yaml
恢复工作前的检查清单：文档文件存在、所有端点已记录、请求/响应 Schema 已定义、所有操作提供示例、安全要求已记录、文档验证通过、变更已提交到分支。
适用场景
适用于使用 Express、Fastify、NestJS、FastAPI、Flask、Go 等框架且维护 Swagger/OpenAPI 文档的项目，在 API 代码变更时确保文档同步。
限制与跳过条件
以下情况可跳过该技能：变更纯属内部实现（无 API 表面变化）、仅修改测试文件、仅修改文档本身、项目没有 API（如 CLI 工具、库等）。
集成
该技能与 documentation-audit（完整文档同步）、issue-driven-development（实现期间触发）、comprehensive-review（验证文档完整性）协同工作。