Redocly CLI OpenAPI 检查与文档生成器

为什么需要这个工具

团队维护 API 规格文件时常见两类问题：一是 YAML 或 JSON 描述语法正确但语义不符合规范，比如缺少必填字段、引用了未定义的组件；二是规格与实际实现逐渐脱节，文档生成后很快过时。Redocly CLI 把 lint、validate、bundle 和文档生成压进一条命令链，让这些问题在 CI 阶段就能暴露，而不是等部署后才被发现。

核心能力与关键步骤

Lint 和 validate 是两条独立路径：lint 按规则集给出风格与治理建议，validate 只检查规范本身的结构完整性。执行 redocly lint path-to-root-file.yaml 时，工具会解析入口文件，自动展开 $ref 引用与继承关系，再套用规则集输出报告。

文档生成直接从同一入口产出静态站点，适合在 PR 预览中贴链接，让 reviewer 对照具体改动。

多格式兼容覆盖 OpenAPI 3.0/3.1/3.2、Swagger 2.0、AsyncAPI 3.0 和 Arazzo 1.0，迁移期的团队不需要额外转换器就能跑通检查流程。

适用边界

• Node 版本要求较高：最低需 Node.js 22.12.0、NPM 10.9.2，旧的 CI 镜像需要先升级
• Docker 模式适合临时验证，正式 CI 流水线建议全局安装，避免每次运行都拉镜像
• 规则集需要团队自行维护，工具本身不提供现成的治理策略
• 只处理规格文件层面的问题，无法替代端到端的契约测试