OpenAPI 规范验证器

要解决什么问题

当 API 团队把 OpenAPI 3.x 当作代码维护时，规范写错、约束不一致、生成 SDK 类型缺失，以及版本升级悄悄引入 breaking change，都会累积成返工。这个技能把校验流程从手工检查变成可重复的工程动作。

• 校验文档结构是否合法，减少因 required、路径参数、响应定义不一致导致的歧义
• 按规则集 lint 命名、描述、错误响应和安全声明，让团队约定落到 spec 上
• 从 OpenAPI 文档生成类型安全客户端，避免手写 DTO 与实际接口漂移
• 对比旧版与新版 OpenAPI，识别字段删除、必填变化、路径调整等破坏性变更

技能如何工作

它围绕 swagger-parser、@stoplight/spectral、openapi-typescript、oasdiff 和 Redocly CLI 组织，工作流分为三层。

• 解析与校验：读取 OpenAPI 3.x 文档，检查引用、结构、必填字段和规范合法性；Node.js 场景中 swagger-parser 更常配合 CommonJS 使用。
• lint 与治理：Spectral 把团队规则转成可执行检查，Redocly CLI 可辅助诊断和预览文档结构。
• 生成与对比：用 openapi-typescript 产出类型安全的客户端或类型声明；用 oasdiff 比对两个规范版本，输出 breaking change 风险。

适用边界

适合 OpenAPI 3.x 文档已经纳入版本管理、需要自动化校验和 API 演进治理的项目。它不替代接口测试，也不能证明运行时行为一定正确；规则质量取决于团队定义的规则集，破坏性变更结论也要结合业务语义判断。