redocly/openapi-cli

OpenAPI 3 CLI工具箱镜像

概述

该镜像提供了一套基于OpenAPI 3规范的命令行工具集，专注于API文档的验证与打包功能。旨在帮助开发者高效检查API文档的规范性、完整性，并能将分散的文档文件合并为单一规范文件，简化API文档的管理与分发流程。

核心功能

• OpenAPI 3文档验证：全面检查API文档的语法正确性、规范合规性，自动识别潜在错误与不规范定义
• 文档打包合并：支持将引用外部文件（如JSON/YAML片段）的OpenAPI文档合并为单个完整规范文件，便于分享与部署

使用场景

• API开发阶段：在API设计与开发过程中验证文档正确性，确保符合OpenAPI 3标准
• CI/CD流程集成：作为自动化测试环节的一部分，在构建过程中自动验证API文档质量
• 文档发布准备：将多文件组织的API文档打包为单一文件，用于文档平台发布或第三方集成

使用方法

基础使用（Docker Run）

通过挂载本地文档目录到容器，执行验证或打包命令：

验证OpenAPI文档

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/openapi-toolbox validate /app/openapi.yaml

• --rm：容器运行结束后自动清理
• -v $(pwd):/app：将当前工作目录挂载到容器内/app路径
• validate /app/openapi.yaml：对指定路径的OpenAPI文档执行验证

打包OpenAPI文档

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/openapi-toolbox bundle /app/openapi.yaml -o /app/bundled-openapi.yaml

• bundle：启动文档打包功能
• -o /app/bundled-openapi.yaml：指定打包后的输出文件路径，文件将保存到本地挂载目录

常用命令参数

• validate <file_path>：验证指定路径的OpenAPI文档
• bundle <input_file> -o <output_file>：打包输入文档并输出到指定路径
• --help：查看完整命令列表及参数说明
• --version：查看工具版本信息