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.
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.
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-constraintspara código Python moderno. - Agregar un script
backend/scripts/generate_models.shque 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.
Notes
- Marcar los archivos auto-generados con un comentario
# AUTO-GENERATED - DO NOT EDITen 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.