| name | bk-apigateway-openapi-check |
| description | 检查 API 代码实现、YAML 网关资源定义、API 文档三者是否一致。当用户请求检查 API 一致性、校验代码和文档匹配、check api consistency、check yaml matches code、openapi 一致性检查、网关资源定义检查、API 文档对齐、检查 operationId 一致性、检查 backend 路径、grant_permissions 检查、MCP Server 配置检查、鉴权配置检查时使用。Actions: validate, check, analyze, fix. Triggers: api-consistency-check, 检查 API 一致性, 检查代码和文档匹配, check api consistency, check yaml matches code, openapi 检查, 网关资源检查, 文档对齐检查, operationId 检查, backend 路径检查, 三层一致性, YAML 代码文档一致性. |
IRON LAW: 检查操作均为只读，禁止直接修改 YAML 资源定义或代码路由。--fix 仅允许生成文档模板。每条检查结果必须包含具体的 operationId 和问题描述，禁止输出模糊结论。
Red Flags（立即停止并回退）：
Workflow Checklist
工具速查
| 需求 | 命令 |
|---|
| 检查全部 | python scripts/check_api_consistency.py |
| 按范围检查 | python scripts/check_api_consistency.py --scope v2_sync |
| 检查单个 API | python scripts/check_api_consistency.py --api v2_sync_gateway |
| JSON 输出 | python scripts/check_api_consistency.py --json |
| 生成缺失文档 | python scripts/check_api_consistency.py --fix |
| 指定项目路径 | python scripts/check_api_consistency.py --project-dir /path/to/project |
Scope 说明
| scope | YAML tags | 代码目录 | 说明 |
|---|
all | 全部 | 全部 | 默认 |
v2_open | v2+open | apis/v2/open/ | 开放 API |
v2_inner | v2+inner | apis/v2/inner/ | 内部 API |
v2_sync | v2+sync | apis/v2/sync/ | 同步 API |
三层关系
operationId (唯一标识)
├── YAML: bk-apigateway-resources.yaml → paths[path][method].operationId
├── 代码: urls.py → views.py → serializers.py
└── 文档: apidocs/zh/{operationId}.md
详细文件引用和路径映射见 references/file-reference.md。
检查项概览
| # | 检查项 | 核心关注点 |
|---|
| CHECK-1 | 存在性 | 三层都有定义 |
| CHECK-2 | 路径一致性 | YAML path ↔ 代码 URL ↔ backend.path |
| CHECK-3 | HTTP 方法 | YAML method ↔ View method |
| CHECK-4 | 请求参数 | YAML parameters ↔ Serializer 字段 ↔ 文档 |
| CHECK-5 | 响应参数 | YAML response ↔ Serializer 输出 ↔ 文档 |
| CHECK-6 | 鉴权配置 | isPublic / authConfig ↔ permission_classes |
| CHECK-7 | grant_permissions | 授权的资源是否存在 |
| CHECK-8 | MCP Server | resource_names 是否存在，数量是否匹配 |
每项检查的详细判定规则和严重度见 references/check-criteria.md。
已知特殊 case 见 references/special-cases.md。
确认门控
修复前确认 ⚠️ REQUIRED
执行 --fix 前，向用户展示：缺失文档清单 → 修复策略（仅生成模板）→ 影响范围（新增文件列表）。获取明确确认后执行。
Anti-Patterns
- 禁止直接修改 YAML 或代码 — 检查工具为只读，修复由人工确认后执行
- 禁止对 core-api / mcp-proxy backend 报告代码缺失 — 后端不指向 dashboard
- 禁止混淆 WARNING 和 ERROR — WARNING 不导致功能故障
- 禁止遗漏特殊 case — 见 references/special-cases.md
- 禁止输出模糊结论 — 每条结果必须包含 operationId 和问题描述
- 禁止在生产环境运行
--fix — 仅在本地开发环境执行
Pre-Delivery Checklist
相关资源
scripts/
scripts/check_api_consistency.py — 主检查脚本
references/
references/check-criteria.md — CHECK-1~8 详细判定规则与严重度references/file-reference.md — 关键文件路径与三层映射关系references/special-cases.md — 已知特殊 case 白名单
技能版本: 1.1.0
最后更新: 2026-05-15
