api-documentation

用途

该技能确保所有 API 变更都反映到 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 文档：

• openapi.yaml（YAML，OpenAPI 3.x）
• openapi.json（JSON，OpenAPI 3.x）
• swagger.yaml（YAML，Swagger 2.0）
• swagger.json（JSON，Swagger 2.0）
• docs/api.yaml（YAML，OpenAPI 3.x）
• api/openapi.yaml（YAML，OpenAPI 3.x）

使用方式

技能启动时会声明："I'm using api-documentation to verify Swagger/OpenAPI sync."

执行流程分为四步：

1. 检测 API 变更：通过 git diff --name-only HEAD~1 检查常见 API 文件模式（routes、controllers、api、handlers、.controller.ts、_router.py）以及 schema/DTO/model 变更。
2. 查找文档文件：依次查找上述文档位置，若未找到则报错并提示触发 documentation-audit 技能。
3. 验证同步：从代码中提取端点（如 @Get、@Post 等装饰器），从 OpenAPI 文档中提取路径，使用 comm 比较差异，检测代码中存在但文档中缺失的端点。
4. 处理漂移：若检测到漂移，输出暂停状态，列出缺失的端点及其代码位置，要求调用 documentation-audit 技能、更新 Swagger/OpenAPI 文档，并在同步完成后恢复工作。

文档要求

更新 API 文档时，每个端点必须包含：

• summary：端点简短描述
• description：详细说明
• parameters：所有路径/查询/请求头参数
• requestBody：请求 Schema 及示例
• responses：所有响应码及 Schema
• tags：用于组织的分组
• security：认证要求

每个端点还必须提供：请求示例（POST/PUT/PATCH）、成功响应示例、错误响应示例。

验证

更新文档后，可使用以下命令验证：

npx @apidevtools/swagger-cli validate openapi.yaml

或使用 yq 进行基本结构检查：

yq 'has("openapi") and has("paths") and has("info")' openapi.yaml

恢复工作前的检查清单

• API 文档文件存在
• 所有端点均已记录
• 请求/响应 Schema 已定义
• 所有操作均提供示例
• 安全要求已记录
• 文档验证通过
• 变更已提交到分支

集成

该技能与以下技能协同：

• documentation-audit：完整文档同步
• issue-driven-development：在实现期间触发
• comprehensive-review：验证文档完整性

何时可跳过

以下情况可跳过该技能：

• 变更纯属内部（无 API 表面变化）
• 仅修改测试文件
• 仅修改文档本身
• 项目没有 API（如 CLI 工具、库等）