redocly/cli

Redocly CLI

Redocly CLI 是 @Redocly 提供的开源命令行工具，具备 OpenAPI 增强功能。可用于构建、管理和质量检查 OpenAPI 描述，配置和执行 API 治理，以及发布美观的 API 文档。支持 OpenAPI 3.1、3.0 和 OpenAPI 2.0（旧版 Swagger 格式）。

特性

• API 治理：确保每次修订的 API 都符合标准。现成的规则集、内置及可配置规则让您能够为每个 API 定制适合的 API 标准。
• 优质 API 文档：使用开源 Redoc 或托管工具创建清晰实用的文档，支持本地预览和静态构建。
• 管理 OpenAPI 文件：将 OpenAPI 描述拆分为逻辑块，合并块以创建单个文件，或合并现有定义。
• 转换 OpenAPI：发布端点子集，或使用装饰器通过添加、修改或删除内容来增强现有 OpenAPI。

安装

拉取镜像：

docker pull redocly/cli

Redocly CLI 需要文件访问权限，因此使用此命令时需挂载包含配置和 OpenAPI 文件的目录。例如，要检查当前工作目录中的文件，使用以下命令：

shell
docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml

使用方法

阅读详细文档，并将 redocly 命令替换为 docker run redocly/cli。运行命令时请记住挂载 Docker 需要访问的目录。

获取命令帮助：

docker run redocly/cli --help

生成 API 参考文档

Redocly CLI 是渲染 API 参考文档的理想工具。它使用开源 https://github.com/redocly/redoc 构建文档。使用如下命令：

docker run --rm -v $PWD:/spec redocly/cli build-docs openapi.yaml

API 参考文档默认输出为 redoc-static.html。您可以通过多种方式自定义。阅读主要文档 获取更多信息。

检查 API 描述是否符合标准

使用 lint 命令检查 API 是否符合预期标准，确保每个 API 版本的质量。API 检查器设计为即使对大型文档也能快速运行，因此易于在本地、CI 或任何需要的地方执行。它还专为人类设计，提供有意义的错误消息，帮助您每次都能正确构建 API。尝试以下命令：

docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml

配置规则：您可以根据需要配置规则。无需 JSONPath，只需使用了解 OpenAPI 结构的类型感知表达式。您可以使用 内置规则 组合理想的 API 标准，或使用工具构建自定义规则。

格式化输出：您可以根据需要格式化输出，stylish 输出如名称所示美观，但如果需要 JSON 或 Checkstyle 输出以集成其他工具，我们也提供支持。

支持多文件：无需合并 API 描述即可检查，只需提供入口点，Redocly CLI 会处理其余部分。

了解更多关于 API 标准和配置 Redocly 规则的信息。

数据收集

此工具 收集数据 以帮助 Redocly 改进产品和服务。您可以通过将 REDOCLY_TELEMETRY 环境变量设置为 off 来选择退出。

社区

Redocly CLI 是一个开源项目。在 https://github.com/Redocly/redocly-cli 找到我们并加入社区。