OpenAPI规范校验器

要解决的痛点

手写的 OpenAPI 3.1 文档很少一开始就干净。字段名拼错、$ref 指向不存在的组件、description 缺失、约束与实际返回体不一致，这类问题在 CI 之外往往没人发现，等到下游客户端按文档生成代码时才会炸。更麻烦的是版本演进：v1 到 v2 悄悄删掉一个字段、把 optional 改成必填，破坏性变更常常混在一次「常规重构」里提交进去。

它是怎么工作的

这个技能把校验拆成三层，各司其职：

• 语法与结构校验：用 swagger-parser 解析文档，检查 $ref 能否解析、结构是否符合 OpenAPI 3.1 的约束，解析不过的地方直接暴露行号与路径。
• 规则检查：用 Spectral 的 ruleset 引擎做 lint，对命名风格、描述完整性、operationId 是否缺失等可定制规则逐条判定，而不是只告诉你「文档不合法」。
• 版本对比：接入 oasdiff，把新旧两份 spec 喂给它，输出破坏性变更清单，例如移除字段、收窄 nullable、把可选参数改为必填。

典型的使用方式是在提交或发布前先跑一遍校验，再把当前版本与上一个稳定版本的 spec 交给 oasdiff 做 diff，把「破坏性变更」变成一条必须确认的结论，而不是留给调用方线上报错。

边界与注意点

• 工具只负责判定和报告，不会替你修复文档；规则松紧取决于所用的 Spectral ruleset，不同团队可能需要先定基线再收敛。
• oasdiff 的破坏性判定基于规范定义，语义上兼容但实际行为变化的接口它同样看不出来，这类仍需要人工 review。
• 上游 SwaggerUI 组件会通过 Scarf 收集匿名安装统计，若部署环境对出网行为有要求，需要提前确认。
• 该技能抽取自上游文档仓库，核心实现依赖 Spectral、swagger-parser 与 oasdiff 三个外部工具，请先确认本机运行环境齐备再接入流程。