OpenAPI 规范校验器

校验 OpenAPI 规范，先解决三个具体问题

手动维护 OpenAPI 3.0/3.1 规范，常见的问题不止“格式写错了”。

• 结构错误往往到集成或文档生成阶段才暴露，比如 paths、operations 缺少必要字段，或 requestBody、response 的描述不完整。
• 团队升级规范版本时，容易遗漏兼容性变化；一个字段从可选变必填、一个响应码被删除，都可能影响下游客户端和服务调用方。
• 规则靠代码 review 很难稳定执行，不同成员对命名、描述、扩展字段的要求理解不一致，最终规范风格随项目迭代逐渐失控。

技能如何完成校验与迁移检查

这个技能将规范校验拆成可复用的三步。

• 使用 Spectral CLI rules 加载适合 OpenAPI 的预定义规则集，对规范文件做结构化检查，覆盖字段约束、命名约定、文档完整性等工程化要求。
• 使用 Swagger Parser library 对 OpenAPI 3.0/3.1 规范做解析与校验，帮助在进入 API 实现或文档发布前发现语法与结构问题。
• 对比不同版本规范，检测可能影响现有调用方的 breaking changes，并基于差异生成 migration guide，让团队明确需要修改的位置和兼容风险。

在工程流程中，它可以放在 CI 或 pre-commit 阶段：规范文件发生变化时先跑校验，再根据报告中的问题修正结构；如果涉及版本升级或接口调整，再根据迁移指南更新调用方与文档。这样可以减少“文档看起来正常，但实际不可用”的隐性成本。

适用边界与注意点

• 运行环境需要 Node.js，技能能力依赖于 Spectral CLI 与 Swagger Parser 的规则和解析结果。
• 迁移检测的准确度取决于输入的两个规范版本是否完整、可比对；如果只提供片段，生成的迁移指南可能遗漏上下文。
• 规则集可以提升一致性，但不会替团队定义业务语义；项目中的特殊命名、扩展字段或合规要求仍需自行维护配置。
• 适合规范维护、版本升级、接口评审和文档质量检查场景，但不能替代端到端 API 测试。