datamodel_code_generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

datamodel_code_generator

Herramienta que genera automáticamente modelos Pydantic a partir de especificaciones OpenAPI o JSON Schema. Permite mantener una fuente única de verdad para los contratos de datos del sistema, evitando inconsistencias entre la documentación de la API y el código.

可根据OpenAPI或JSON Schema规范自动生成Pydantic模型的工具，支持为系统的数据契约维护单一可信数据源，避免API文档和代码之间出现不一致问题。

When to use

适用场景

Usar cuando se trabaje con APIs externas de fallback (AWS Rekognition, Google Vision, Mindee) que proveen especificaciones OpenAPI, o cuando se defina primero el schema JSON y se quiera generar código Python automáticamente. También útil al integrar nuevos servicios al pipeline de verificación KYC.

适用于对接提供OpenAPI规范的备用外部API（AWS Rekognition、Google Vision、Mindee），或是先定义JSON Schema再自动生成Python代码的场景，在KYC验证流水线集成新服务时也非常实用。

Instructions

使用说明

Instalar la herramienta:
```
pip install datamodel-code-generator
```
.
Crear un directorio
```
backend/schemas/sources/
```
para almacenar los JSON Schema u OpenAPI specs fuente.

Generar modelos desde JSON Schema:

datamodel-codegen --input schema.json --output models.py --output-model-type pydantic_v2.BaseModel

Generar modelos desde OpenAPI:

datamodel-codegen --input openapi.yaml --output models.py --input-file-type openapi

Configurar opciones de generación:

--use-standard-collections --use-union-operator --field-constraints

para código Python moderno.

Agregar un script
```
backend/scripts/generate_models.sh
```
que regenere todos los modelos desde las specs fuente de forma reproducible.
Integrar la generación en CI para verificar que los modelos generados están sincronizados con las specs: comparar el output del generador con los archivos committeados.
Personalizar los modelos generados mediante herencia en archivos separados, nunca editando directamente los archivos auto-generados.

安装工具：
```
pip install datamodel-code-generator
```
创建
```
backend/schemas/sources/
```
目录，用于存储源JSON Schema或OpenAPI规范

从JSON Schema生成模型：

datamodel-codegen --input schema.json --output models.py --output-model-type pydantic_v2.BaseModel

从OpenAPI生成模型：

datamodel-codegen --input openapi.yaml --output models.py --input-file-type openapi

配置生成选项：使用

--use-standard-collections --use-union-operator --field-constraints

参数生成现代Python代码

添加
```
backend/scripts/generate_models.sh
```
脚本，可基于源规范可复现地重新生成所有模型
将生成流程集成到CI中，验证生成的模型与规范同步：对比生成器的输出与已提交的文件
不要直接编辑自动生成的文件，可通过在独立文件中继承的方式自定义生成的模型

Notes

注意事项

Marcar los archivos auto-generados con un comentario
```
# AUTO-GENERATED - DO NOT EDIT
```
en la primera línea para evitar ediciones manuales accidentales.
Cuando la fuente de verdad sea el código Pydantic (no el schema), usar el flujo inverso: exportar JSON Schema desde Pydantic con
```
model_json_schema()
```
.
Configurar pre-commit hooks para verificar que los modelos generados están actualizados antes de cada commit.

在自动生成的文件第一行添加
```
# AUTO-GENERATED - DO NOT EDIT
```
注释标记，避免意外的手动编辑
如果可信数据源是Pydantic代码（而非Schema），则使用反向流程：通过
```
model_json_schema()
```
从Pydantic导出JSON Schema
配置pre-commit钩子，在每次提交前验证生成的模型是否为最新版本