OpenAPI 文件打包校验

它解决的问题

把 OpenAPI 规范按文件拆开维护是常见做法：$ref 指向同目录下的 paths.yaml、components.yaml，或者直接引用远程 URL。人读起来很清晰，工具却拿到一堆散落的引用。文档站点不知道该加载哪些文件，代码生成器经常报 Could not resolve reference，CI 里做规范校验的步骤也拿不到一份自包含的快照。结果是「在我机器上能跑」变成常态：本地能拼出来的规范，推到流水线上就缺文件。

它如何工作

这个技能基于 swagger-cli，做两件事：bundle 与 validate。

• 解析与内联：从入口文件出发，递归读取所有本地或远程 $ref，把被引用的文档替换为实际内容，生成单个 bundle.yaml 或 bundle.json。远程引用在这一步被拉取并固化，产物不再依赖网络可达性。
• 校验：对 bundle 结果做结构检查，包括必需字段、类型匹配、paths 与 operations 的合法性。校验不通过时会给出具体位置的报错，而不是笼统的解析失败。
• 面向发布：产物是一份完整、自包含的规范，可以直接作为文档站的源文件、代码生成器的输入，或者 CI 中校验步骤的固定工件。
• 接入版本控制：上游提到 swagger-cli validate 可以作为 git pre-commit 钩子的一环，让格式问题在提交前被拦住，避免不合规的规范进入仓库。

适用边界与注意点

前提是本地要有 Node.js 环境，通过 npx 或全局安装均可调用，无需额外配置服务端。

它解决的是打包与校验，不替代规范设计本身：接口划分不合理、语义模糊的问题，bundle 之后依然存在。远程 $ref 会引入外部依赖，一旦上游地址变动或失效，产物可能已经过时，建议把关键引用固化下来或在 CI 中定期检查。

另外要区分 bundle 与 validate 的用途——想确认规范「正确」，跑 validate；想确认它「能被人和工具完整读取」，跑 bundle。两者互补，通常先 bundle 再 validate，才能拿到一份既自包含又结构合规的产物。