chatwork/openapi2jsonschema

openapi2jsonschema Docker镜像文档

1. 镜像概述和主要用途

openapi2jsonschema 是一个 Docker 化的工具镜像，基于 https://github.com/instrumenta/openapi2jsonschema 项目构建，用于将 OpenAPI 规范文件（支持 OpenAPI 2.0/3.0 等版本）转换为 JSON Schema 格式。该镜像提供了便捷的命令行接口，可直接在容器环境中运行，避免本地环境依赖配置，适用于需要快速转换 OpenAPI 规范以生成 JSON Schema 的开发场景。

2. 核心功能和特性

• 核心功能：将 OpenAPI 规范文件（.yaml 或 .json 格式）转换为符合 JSON Schema 标准的输出文件。
• 多版本支持：兼容 OpenAPI 2.0（Swagger）和 OpenAPI 3.0 规范。
• 轻量便捷：基于 Docker 容器化，无需本地安装依赖，直接通过命令行调用。
• 灵活配置：支持通过命令行参数自定义输入文件、输出路径、OpenAPI 版本等转换规则（完整参数需参考项目 GitHub 文档）。

3. 使用场景和适用范围

适用场景

• API 开发中，需基于 OpenAPI 规范生成 JSON Schema 用于请求/响应数据验证。
• 生成客户端 SDK 时，通过 JSON Schema 定义数据结构类型。
• API 文档自动化，将 OpenAPI 中的数据模型转换为 JSON Schema 格式嵌入文档。
• CI/CD 流程中集成，自动校验 OpenAPI 规范与 JSON Schema 的一致性。

适用范围

• 需要处理 OpenAPI 规范文件的开发者或开发团队。
• 依赖 JSON Schema 进行数据验证、类型定义的项目。
• 追求环境一致性、避免本地依赖冲突的开发流程。

4. 使用方法和配置说明

基本使用流程

1. 准备 OpenAPI 文件：确保本地存在待转换的 OpenAPI 规范文件（如 openapi.yaml 或 openapi.json）。
2. 挂载本地目录：通过 Docker 卷挂载本地目录至容器内，使工具可访问 OpenAPI 文件。
3. 执行转换命令：通过 docker run 调用镜像，传入命令行参数指定转换规则。

核心命令说明

容器内工作目录默认为 /openapi2jsonschema，建议将本地 OpenAPI 文件所在目录挂载至此路径，便于工具直接读取。

查看帮助信息

bash
docker run -v ${PWD}:/openapi2jsonschema docker.xuanyuan.run/chatwork/openapi2jsonschema --help

• 说明：挂载当前目录（${PWD}）至容器内 /openapi2jsonschema，执行 --help 查看所有支持的命令行参数。

转换 OpenAPI 文件为 JSON Schema

假设本地当前目录下有 openapi.yaml（OpenAPI 3.0 规范），需转换为 JSON Schema 并输出至 ./output 目录：

bash
docker run -v ${PWD}:/openapi2jsonschema docker.xuanyuan.run/chatwork/openapi2jsonschema \
  --input openapi.yaml \
  --output /openapi2jsonschema/output \
  --openapi-version 3.0

• 参数说明：
  • --input：指定输入的 OpenAPI 文件路径（容器内路径，需在挂载目录下）。
  • --output：指定输出 JSON Schema 的目录路径（容器内路径，对应本地挂载目录下的 output 文件夹）。
  • --openapi-version：指定 OpenAPI 规范版本（如 2.0 或 3.0）。

命令行参数参考

完整参数列表请参考 https://github.com/instrumenta/openapi2jsonschema%EF%BC%8C%E5%B8%B8%E7%94%A8%E5%8F%82%E6%95%B0%E5%8C%85%E6%8B%AC%EF%BC%9A

• --input：输入 OpenAPI 文件路径（必填）。
• --output：输出 JSON Schema 目录路径（默认当前目录）。
• --openapi-version：OpenAPI 规范版本（如 2.0、3.0）。
• --prefix：为生成的 JSON Schema 添加 URI 前缀。
• --strict：启用严格模式，严格校验 OpenAPI 规范。

5. Docker 部署方案示例

5.1 单命令部署（docker run）

通过 docker run 直接执行转换任务，适用于临时或单次转换需求。

示例：转换当前目录下的 OpenAPI 3.0 文件

bash
# 假设本地当前目录有 openapi-v3.yaml，输出至当前目录的 schema 文件夹
docker run -v ${PWD}:/openapi2jsonschema docker.xuanyuan.run/chatwork/openapi2jsonschema \
  --input openapi-v3.yaml \
  --output /openapi2jsonschema/schema \
  --openapi-version 3.0 \
  --strict

5.2 Docker Compose 配置（docker-compose.yml）

适用于需要频繁执行转换或集成到项目流程中的场景，通过 docker-compose 简化命令。

yaml
version: '3'
services:
  openapi2jsonschema:
    image: docker.xuanyuan.run/chatwork/openapi2jsonschema
    volumes:
      - ./openapi:/openapi2jsonschema  # 挂载本地 ./openapi 目录至容器工作目录
    command: >
      --input openapi-spec.yaml  # 输入文件（位于 ./openapi 目录下）
      --output /openapi2jsonschema/output  # 输出目录（映射至本地 ./openapi/output）
      --openapi-version 3.0

使用方法：

1. 将上述配置保存为 docker-compose.yml。
2. 在 ./openapi 目录下放置 openapi-spec.yaml。
3. 执行 docker-compose up，转换后的 JSON Schema 将输出至 ./openapi/output 目录。

6. 注意事项

• 文件权限：挂载目录时需确保本地用户对挂载目录有读写权限，避免容器内无法访问或写入文件。
• OpenAPI 版本兼容性：需通过 --openapi-version 指定正确的 OpenAPI 版本，否则可能导致转换失败。
• 完整参数参考：本文仅列出常用参数，完整功能及参数请查阅 https://github.com/instrumenta/openapi2jsonschema%E3%80%82