datamodel-code-generator

这个代码生成器从 openapi 文件和其他文件创建 pydantic v1 和 v2 模型、dataclasses.dataclass、typing.TypedDict 和 msgspec.Struct。

帮助

查看文档了解更多详情。

快速安装

安装 datamodel-code-generator:

$ pip install datamodel-code-generator

简单用法

你可以从本地文件生成模型。

$ datamodel-codegen --input api.yaml --output model.py

<details> <summary>api.yaml</summary>

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: 列出所有宠物
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: 一次返回多少项 (最大100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: 宠物的分页数组
          headers:
            x-next:
              description: 下一页响应的链接
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: 意外错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
    post:
      summary: 创建一个宠物
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: 空响应
        default:
          description: 意外错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
  /pets/{petId}:
    get:
      summary: 特定宠物的信息
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: 要检索的宠物的id
          schema:
            type: string
      responses:
        '200':
          description: 对有效请求的预期响应
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: 意外错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    apis:
      type: array
      items:
        type: object
        properties:
          apiKey:
            type: string
            description: 用作数据集参数值
          apiVersionNumber:
            type: string
            description: 用作版本参数值
          apiUrl:
            type: string
            format: uri
            description: "描述数据集字段的URL"
          apiDocumentationUrl:
            type: string
            format: uri
            description: 每个API的API控制台的URL

</details> <details> <summary>model.py</summary>

# 由datamodel-codegen生成:
#   文件名:  api.yaml
#   时间戳: 2020-06-02T05:28:24+00:00

from __future__ import annotations

from typing import List, Optional

from pydantic import AnyUrl, BaseModel, Field


class Pet(BaseModel):
    id: int
    name: str
    tag: Optional[str] = None


class Pets(BaseModel):
    __root__: List[Pet]


class Error(BaseModel):
    code: int
    message: str


class Api(BaseModel):
    apiKey: Optional[str] = Field(
        None, description='用作数据集参数值'
    )
    apiVersionNumber: Optional[str] = Field(
        None, description='用作版本参数值'
    )
    apiUrl: Optional[AnyUrl] = Field(
        None, description="描述数据集字段的URL"
    )
    apiDocumentationUrl: Optional[AnyUrl] = Field(
        None, description='每个API的API控制台的URL'
    )


class Apis(BaseModel):
    __root__: List[Api]

</details>

支持的输入类型

• OpenAPI 3 (YAML/JSON, OpenAPI 数据类型);
• JSON Schema (JSON Schema Core/JSON Schema 验证);
• JSON/YAML/CSV 数据 (将被转换为 JSON Schema);
• Python 字典 (将被转换为 JSON Schema);
• GraphQL schema (GraphQL Schemas 和 Types);

支持的输出类型

• pydantic.BaseModel;
• pydantic_v2.BaseModel;
• dataclasses.dataclass;
• typing.TypedDict;
• msgspec.Struct;
• 从你的 jinja2 模板生成的自定义类型;

赞助商

<table> <tr> <td valign="top" align="center"> <a href="https://github.com/JetBrainsOfficial"> <img src="https://avatars.githubusercontent.com/u/60931315?s=100&v=4" alt="JetBrains Logo" style="width: 100px;"> <p>JetBrains</p> </a> </td> <td valign="top" align="center"> <a href="https://github.com/astral-sh"> <img src="https://avatars.githubusercontent.com/u/115962839?s=200&v=4" alt="Astral Logo" style="width: 100px;"> <p>Astral</p> </a> </td> <td valign="top" align="center"> <a href="https://github.com/DataDog"> <img src="https://avatars.githubusercontent.com/u/365230?s=200&v=4" alt="Datadog, Inc. Logo" style="width: 100px;"> <p>Datadog, Inc.</p> </a> </td> </tr> </table>

使用datamodel-code-generator的项目

这些开源项目使用datamodel-code-generator生成大量模型。 查看以下链接的项目以获取真实世界的示例和灵感。

• airbytehq/airbyte
  • 生成Python、Java/Kotlin和Typescript协议模型
• apache/iceberg
  • 生成Python代码 make generate
• argoproj-labs/hera
  • Makefile
• awslabs/aws-lambda-powertools-python
  • 在官方文档中推荐用于高级使用场景
• DataDog/integrations-core
  • 配置模型
• hashintel/hash
  • codegen.sh
• IBM/compliance-trestle
  • 从OSCAL schemas构建模型。
• Netflix/consoleme
  • 如何从Swagger规范生成模型？
• Nike-Inc/brickflow
  • 代码生成工具./tools/gen-bundle.sh
• open-metadata/OpenMetadata
  • Makefile
• PostHog/posthog
  • 通过npm run生成模型
• SeldonIO/MLServer
  • generate-types.sh

安装

安装 datamodel-code-generator:

类型自定义:
  --base-class BASE_CLASS
                        基类 (默认: pydantic.BaseModel)
  --enum-field-as-literal {all,one}
                        将枚举字段解析为字面量。all: 所有枚举字段类型都是 Literal。
                        one: 当枚举只有一个可能值时,字段类型为 Literal
  --field-constraints   使用字段约束而不是 con* 注解
  --set-default-enum-member
                        将枚举成员设置为枚举字段的默认值
  --strict-types {str,bytes,int,float,bool} [{str,bytes,int,float,bool} ...]
                        使用严格类型
  --use-annotated       为 Field() 使用 typing.Annotated。同时,将启用 `--field-constraints` 选项
  --use-generic-container-types
                        使用泛型容器类型进行类型提示 (typing.Sequence,
                        typing.Mapping)。如果设置了 `--use-standard-collections` 选项,则
                        从 collections.abc 而不是 typing 导入
  --use-non-positive-negative-number-constrained-types
                        使用 Non{Positive,Negative}{FloatInt} 类型代替
                        相应的 con* 约束类型
  --use-one-literal-as-default
                        对单个字面量字段使用一个字面量作为默认值
  --use-standard-collections
                        使用标准集合进行类型提示 (list, dict)
  --use-subclass-enum   当枚举有类型时(int, float, bytes, str),将 Enum 类定义为带有字段类型的子类
  --use-union-operator  使用 | 运算符表示 Union 类型 (PEP 604)
  --use-unique-items-as-set
                        当字段属性有 `uniqueItems` 时,将字段类型定义为 `set`

字段自定义:
  --capitalise-enum-members, --capitalize-enum-members
                        将枚举成员字段名首字母大写
  --empty-enum-field-name EMPTY_ENUM_FIELD_NAME
                        当枚举值为空时设置字段名 (默认: `_`)
  --field-extra-keys FIELD_EXTRA_KEYS [FIELD_EXTRA_KEYS ...]
                        向字段参数添加额外键
  --field-extra-keys-without-x-prefix FIELD_EXTRA_KEYS_WITHOUT_X_PREFIX [FIELD_EXTRA_KEYS_WITHOUT_X_PREFIX ...]
                        向字段参数添加带 `x-` 前缀的额外键。额外键会去除 `x-` 前缀
  --field-include-all-keys
                        向字段参数添加所有键
  --force-optional      强制必填字段为可选
  --original-field-name-delimiter ORIGINAL_FIELD_NAME_DELIMITER
                        设置转换为蛇形命名的分隔符。此选项只能与 --snake-case-field 一起使用 (默认: `_` )
  --remove-special-field-name-prefix
                        如果字段名前缀具有特殊含义,则删除该前缀,例如下划线
  --snake-case-field    将驼峰命名的字段名改为蛇形命名
  --special-field-name-prefix SPECIAL_FIELD_NAME_PREFIX
                        当首字符不能用作 Python 字段名时,设置字段名前缀 (默认: `field`)
  --strip-default-none  删除字段上的默认 None 值
  --union-mode {smart,left_to_right}
                        仅用于 pydantic v2 字段的联合模式
  --use-default         即使字段是必填的,也使用默认值
  --use-default-kwarg   对具有默认值的 Field 使用 `default=` 而不是位置参数
  --use-field-description
                        使用模式描述填充字段文档字符串

模型自定义:
  --allow-extra-fields  允许传递额外字段,如果未传递此标志,则禁止额外字段
  --allow-population-by-field-name
                        允许通过字段名填充
  --class-name CLASS_NAME
                        设置根模型的类名
  --collapse-root-models
                        具有根类型字段的生成模型将合并到使用该根类型模型的模型中
  --disable-appending-item-suffix
                        禁用在数组中的模型名称后追加 `Item` 后缀
  --disable-timestamp   禁用文件头部的时间戳
  --enable-faux-immutability
                        启用伪不可变性
  --enable-version-header
                        在文件头部启用包版本
  --keep-model-order    保持生成模型的顺序
  --reuse-model         当模块有相同内容的模型时,在字段上重用模型
  --target-python-version {3.6,3.7,3.8,3.9,3.10,3.11,3.12}
                        目标 Python 版本 (默认: 3.8)
  --treat-dot-as-module
                        将带点的模块名视为模块
  --use-exact-imports   导入确切类型而不是模块,例如: "from .foo import Bar" 而不是 "from . import foo" 和 "foo.Bar"
  --use-pendulum        使用 pendulum 而不是 datetime
  --use-schema-description
                        使用模式描述填充类文档字符串
  --use-title-as-name   使用标题作为模型的类名

模板自定义:
  --aliases ALIASES     别名映射文件
  --custom-file-header CUSTOM_FILE_HEADER
                        自定义文件头
  --custom-file-header-path CUSTOM_FILE_HEADER_PATH
                        自定义文件头文件路径
  --custom-formatters-kwargs CUSTOM_FORMATTERS_KWARGS
                        包含自定义格式化程序 kwargs 的文件
  --custom-template-dir CUSTOM_TEMPLATE_DIR
                        自定义模板目录
  --encoding ENCODING   输入和输出的编码 (默认: utf-8)
  --extra-template-data EXTRA_TEMPLATE_DATA
                        额外的模板数据
  --use-double-quotes   生成的模型使用双引号。如果没有此选项,将使用单引号或您的 black 配置 skip_string_normalization 值
  --wrap-string-literal
                        通过使用 black 的 `experimental-string-processing` 选项包装字符串字面量 (需要 black 20.8b0 或更高版本)

仅 OpenAPI 选项:
  --openapi-scopes {schemas,paths,tags,parameters} [{schemas,paths,tags,parameters} ...]
                        OpenAPI 模型生成的范围 (默认: schemas)
  --strict-nullable     将默认字段视为非空字段 (仅 OpenAPI)
  --use-operation-id-as-name
                        使用 OpenAPI 的操作 ID 作为模型的类名
  --validation          已弃用: 启用验证 (仅 OpenAPI)。此选项已弃用,将在未来版本中移除

常规选项:
  --debug               显示调试消息 (需要 "debug"。`$ pip install 'datamodel-code-generator[debug]'`)
  --disable-warnings    禁用警告
  --no-color            禁用彩色输出
  --version             显示版本
  -h, --help            显示此帮助消息并退出

## 相关项目
### fastapi-code-generator
此代码生成器从 openapi 文件创建 [FastAPI](https://github.com/tiangolo/fastapi) 应用程序。

[https://github.com/koxudaxi/fastapi-code-generator](https://github.com/koxudaxi/fastapi-code-generator)

### pydantic-pycharm-plugin
[JetBrains PyCharm 插件](https://plugins.jetbrains.com/plugin/12861-pydantic) 适用于 [`pydantic`](https://github.com/samuelcolvin/pydantic)。

[https://github.com/koxudaxi/pydantic-pycharm-plugin](https://github.com/koxudaxi/pydantic-pycharm-plugin)

## PyPi

[https://pypi.org/project/datamodel-code-generator](https://pypi.org/project/datamodel-code-generator)

## 贡献

有关如何开始,请参阅 `docs/development-contributing.md`!

## 许可证

datamodel-code-generator 根据 MIT 许可证发布。http://www.opensource.org/licenses/mit-license