datamodel-code-generator

镜像概述

datamodel-code-generator是一款代码生成工具，能够从OpenAPI规范、JSON Schema、JSON、YAML、CSV等多种数据源生成Python数据模型，支持Pydantic v1/v2模型、dataclasses.dataclass、typing.TypedDict及msgspec.Struct等多种输出类型。该工具广泛应用于API客户端开发、数据验证、配置文件处理等场景，帮助开发者快速生成类型安全的数据模型代码，减少手动编码工作量。

核心功能与特性

支持的输入类型

• OpenAPI 3规范（YAML/JSON格式）
• JSON Schema（核心规范及验证规范）
• JSON/YAML结构化数据
• CSV文件
• Python字典
• 远程URL（需启用HTTP支持）

支持的输出类型

• pydantic.BaseModel（v1版本）
• pydantic_v2.BaseModel（v2版本）
• dataclasses.dataclass
• typing.TypedDict
• msgspec.Struct
• 自定义Jinja2模板生成的模型

关键特性

• 自动类型推断与转换
• 支持字段名称格式转换（如驼峰式转蛇形命名）
• 可配置的模型基类与字段约束
• 支持远程文件URL解析（需安装HTTP扩展）
• 丰富的命令行选项，支持自定义模型生成规则
• 容器化部署支持（Docker镜像可用）

使用场景

1. API客户端开发：从OpenAPI规范自动生成Pydantic模型，用于API请求/响应数据的序列化与反序列化。
2. 数据验证：基于JSON Schema生成Pydantic模型，实现输入数据的自动校验。
3. 配置文件处理：将JSON/YAML配置文件转换为dataclass或TypedDict，提供类型提示与结构校验。
4. 数据ETL流程：从CSV或JSON数据源生成数据模型，规范数据处理流程中的数据结构。
5. OpenAPI文档同步：当API规范更新时，自动重新生成模型代码，保持客户端与API的一致性。

使用方法

镜像拉取

bash
docker pull koxudaxi/datamodel-code-generator

基本使用（从本地文件生成）

将本地数据源文件（如OpenAPI规范文件）挂载到容器中，生成数据模型代码：

bash
# 示例：从当前目录的api.yaml生成model.py
docker run --rm -v $(pwd):/app koxudaxi/datamodel-code-generator \
  --input /app/api.yaml \
  --output /app/model.py

参数说明：

• --rm：容器退出后自动删除
• -v $(pwd):/app：将当前目录挂载到容器内的/app目录
• --input /app/api.yaml：指定输入文件路径（容器内路径）
• --output /app/model.py：指定输出文件路径（容器内路径）

高级使用（从远程URL生成）

需启用HTTP支持（镜像已预装相关依赖），从远程URL获取数据源并生成模型：

bash
docker run --rm -v $(pwd):/app koxudaxi/datamodel-code-generator \
  --url [***] \
  --output /app/remote_model.py

自定义输出模型类型

指定生成dataclasses.dataclass类型的模型：

bash
docker run --rm -v $(pwd):/app koxudaxi/datamodel-code-generator \
  --input /app/schema.json \
  --output /app/dataclass_model.py \
  --output-model-type dataclasses.dataclass

docker-compose示例

创建docker-compose.yml文件，定义生成任务：

yaml
version: '3'
services:
  generate-model:
    image: koxudaxi/datamodel-code-generator
    volumes:
      - ./:/app
    command: >
      --input /app/api.yaml
      --output /app/model.py
      --snake-case-field  # 将字段名转换为蛇形命名
      --use-field-description  # 从 schema 描述生成字段文档字符串

运行生成命令：

bash
docker-compose run --rm generate-model

主要命令选项

完整命令选项可通过以下命令查看：

bash
docker run --rm koxudaxi/datamodel-code-generator --help

实际应用案例

多个开源项目使用该工具生成数据模型，包括：

• Apache Iceberg：从OpenAPI生成Python客户端模型
• AWS Lambda Powertools：推荐用于高级数据解析场景
• Datadog Integrations Core：生成配置模型用于监控集成
• Netflix ConsoleMe：从Swagger规范生成API客户端模型

许可证

MIT许可证，详见项目仓库。