技能介绍

核心问题

手写的 OpenAPI 3.x 规范常常很快失真：接口代码改了，文档里的 schema 还是旧的；CI 里没有对 spec 做自动化检查，参数类型写错、响应缺少字段、鉴权声明漏配这些问题要到联调甚至线上才被发现。对依赖这份 spec 生成客户端、配置网关或做契约测试的团队来说，这种延迟会直接拖慢集成，也让规范逐渐失去参考价值。

工作方式

这个技能把校验拆成两个层次：先用 swagger-parser 解析 OpenAPI 文档，确认结构可解析、引用完整；再按 Spectral 的 linter 规则逐条扫描，覆盖参数定义、响应 schema、安全要求等常见合规点。

关键步骤包括：

解析并校验文档本身，避免非法 YAML/JSON 或断裂的引用
按规则检查参数类型、必填项、响应 schema 是否与声明一致
核对 security 配置，确认受保护路径都声明了鉴权
生成合规报告，把不合规项按规则名和位置列出

适用边界与注意点

它针对的是 OpenAPI 3.x 文档，不负责运行时流量校验，也不能证明真实接口行为一定符合 spec。项目提供的官方文档链接是通用 OpenAPI 资料，并非该技能的专属使用说明；资料中未自动提取到可落地的安装与用法，因此在接入 CI 或用于敏感流程前，建议先审阅上游项目。报告适合作为契约一致性的技术债参考，仍需配合真实的请求测试或契约测试。