Skip to content

Commit 5c25e38

Browse files
koxudaxipre-commit-ci[bot]github-actions[bot]
authored
docs: Comprehensive documentation improvements with CLI reference enhancements (#2681)
* docs: enhance CLI documentation with related options and new utility section * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: enhance documentation with additional cross-references and new sections * docs: update CLI doc marker validation to include additional linting rules * docs: update CLI doc marker validation to include additional linting rules * docs: update CLI doc marker validation to include additional linting rules * docs: update CLI reference documentation 🤖 Generated by GitHub Actions * docs: update code block syntax in module-exports.md to specify text format * docs: update related options in model-customization and template-customization docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: update CLI reference documentation 🤖 Generated by GitHub Actions * docs: clarify binary type description and improve error handling in CLI documentation generation * docs: correct references to pyproject.toml and update code block syntax in documentation * docs: update CLI reference documentation 🤖 Generated by GitHub Actions * docs: add configuration for ruff in coderabbit.yaml * docs: correct references to pyproject.toml in general-options documentation * docs: update CLI reference documentation 🤖 Generated by GitHub Actions * docs: improve page title cleanup to preserve dots for filenames --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent 18ee0c0 commit 5c25e38

41 files changed

Lines changed: 2957 additions & 128 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.coderabbit.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
2+
reviews:
3+
tools:
4+
ruff:
5+
enabled: true
6+
config_file: "pyproject.toml"

‎README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,10 @@
2525
**👉 [koxudaxi.github.io/datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator)**
2626

2727
- 🖥️ [CLI Reference](https://koxudaxi.github.io/datamodel-code-generator/cli-reference/) - All command-line options
28-
- ❓ [FAQ](https://koxudaxi.github.io/datamodel-code-generator/faq/) - Common questions
2928
- ⚙️ [pyproject.toml](https://koxudaxi.github.io/datamodel-code-generator/pyproject_toml/) - Configuration file
29+
- 🔄 [CI/CD Integration](https://koxudaxi.github.io/datamodel-code-generator/ci-cd/) - GitHub Actions, pre-commit hooks
30+
- 🚀 [One-liner Usage](https://koxudaxi.github.io/datamodel-code-generator/oneliner/) - uvx, pipx, clipboard integration
31+
- ❓ [FAQ](https://koxudaxi.github.io/datamodel-code-generator/faq/) - Common questions
3032

3133
---
3234

@@ -182,6 +184,13 @@ output-model-type = "pydantic_v2.BaseModel"
182184

183185
See [pyproject.toml Configuration](https://koxudaxi.github.io/datamodel-code-generator/pyproject_toml/) for more options.
184186

187+
### 🔄 CI/CD Integration
188+
```bash
189+
datamodel-codegen --check
190+
```
191+
192+
Verify generated code stays in sync with schemas. See [CI/CD Integration](https://koxudaxi.github.io/datamodel-code-generator/ci-cd/) for GitHub Actions and pre-commit hooks.
193+
185194
---
186195

187196
## 💖 Sponsors

‎docs/aliases.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
<!-- related-cli-options: --aliases, --no-alias -->
2+
13
# 🏷️ Field Aliases
24

35
The `--aliases` option allows you to rename fields in the generated models. This is useful when you want to use different Python field names than those defined in the schema while preserving the original names as serialization aliases.

‎docs/ci-cd.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
<!-- related-cli-options: --check, --disable-timestamp, --formatters, --target-python-version, --profile -->
2+
3+
# CI/CD Integration
4+
5+
This guide covers how to use datamodel-code-generator in CI/CD pipelines and development workflows to ensure generated code stays in sync with schemas.
6+
7+
!!! note
8+
The package name is `datamodel-code-generator`, and the CLI command is `datamodel-codegen`.
9+
10+
---
11+
12+
## The `--check` Flag
13+
14+
The `--check` flag verifies that generated code matches existing files without modifying them. If the output would differ, it exits with a non-zero status code.
15+
16+
```bash
17+
datamodel-codegen --check
18+
```
19+
20+
### Success (Exit code 0)
21+
22+
When generated code matches the existing file, the command exits silently with code 0:
23+
24+
```console
25+
$ datamodel-codegen --check
26+
$ echo $?
27+
0
28+
```
29+
30+
### Failure (Exit code 1)
31+
32+
When the schema has changed and the generated code would differ, a unified diff is shown and the command exits with code 1:
33+
34+
```console
35+
$ datamodel-codegen --check
36+
--- models.py
37+
+++ models.py (expected)
38+
@@ -12,3 +12,4 @@
39+
name: Optional[str] = None
40+
age: Optional[int] = None
41+
email: Optional[str] = None
42+
+ active: Optional[bool] = None
43+
$ echo $?
44+
1
45+
```
46+
47+
!!! tip "Best Practice: Use pyproject.toml"
48+
Instead of passing many CLI options, configure all settings in `pyproject.toml`. This keeps CI commands simple, ensures consistency between local development and CI, and makes configuration easier to maintain.
49+
50+
```toml title="pyproject.toml"
51+
[tool.datamodel-codegen]
52+
input = "schemas/api.yaml"
53+
output = "src/models/api.py"
54+
output-model-type = "pydantic_v2.BaseModel"
55+
disable-timestamp = true
56+
```
57+
58+
Then simply run:
59+
60+
```bash
61+
datamodel-codegen --check
62+
```
63+
64+
For projects with multiple schemas, use [named profiles](pyproject_toml.md#named-profiles) to organize configurations by purpose.
65+
66+
**Related:** [`--check`](cli-reference/general-options.md#check), [`--disable-timestamp`](cli-reference/template-customization.md#disable-timestamp), [pyproject.toml Configuration](pyproject_toml.md)
67+
68+
---
69+
70+
## GitHub Actions
71+
72+
### Basic Example
73+
74+
```yaml title=".github/workflows/ci.yml"
75+
name: CI
76+
77+
on:
78+
push:
79+
branches: [main]
80+
pull_request:
81+
82+
jobs:
83+
check-generated-code:
84+
runs-on: ubuntu-latest
85+
steps:
86+
- uses: actions/checkout@v4
87+
88+
- name: Set up Python
89+
uses: actions/setup-python@v5
90+
with:
91+
python-version: "3.14"
92+
93+
- name: Install dependencies
94+
run: pip install datamodel-code-generator
95+
96+
- name: Verify generated models are up-to-date
97+
run: datamodel-codegen --check
98+
```
99+
100+
### Using Profiles for Multiple Schemas
101+
102+
For projects with multiple schemas, use [named profiles](pyproject_toml.md#named-profiles) to organize configurations by purpose:
103+
104+
```toml title="pyproject.toml"
105+
[tool.datamodel-codegen]
106+
output-model-type = "pydantic_v2.BaseModel"
107+
disable-timestamp = true
108+
109+
[tool.datamodel-codegen.profiles.api]
110+
input = "schemas/openapi/api.yaml"
111+
output = "src/models/api.py"
112+
113+
[tool.datamodel-codegen.profiles.events]
114+
input = "schemas/jsonschema/events.json"
115+
output = "src/models/events.py"
116+
input-file-type = "jsonschema"
117+
```
118+
119+
```yaml title=".github/workflows/ci.yml"
120+
- name: Verify API models are up-to-date
121+
run: datamodel-codegen --profile api --check
122+
123+
- name: Verify event models are up-to-date
124+
run: datamodel-codegen --profile events --check
125+
```
126+
127+
### Using uv
128+
129+
If your project uses [uv](https://github.com/astral-sh/uv), you can run the CLI via `uv run`. This example installs the tool ephemerally (no need to add it to your project dependencies):
130+
131+
```yaml title=".github/workflows/ci.yml"
132+
- name: Install uv
133+
uses: astral-sh/setup-uv@v4
134+
135+
- name: Verify generated models are up-to-date
136+
run: uv run --with datamodel-code-generator datamodel-codegen --profile api --check
137+
```
138+
139+
---
140+
141+
## Pre-commit Hook
142+
143+
You can use datamodel-code-generator as a [pre-commit](https://pre-commit.com/) hook to automatically check or regenerate models before commits.
144+
145+
!!! tip
146+
Pin `rev` to a released tag (e.g., `vX.Y.Z`) to keep generated output stable and reproducible across developer machines and CI.
147+
148+
### With pyproject.toml (Recommended)
149+
150+
Configure settings in `pyproject.toml` and use a simple pre-commit hook:
151+
152+
```yaml title=".pre-commit-config.yaml"
153+
repos:
154+
- repo: https://github.com/koxudaxi/datamodel-code-generator
155+
rev: vX.Y.Z
156+
hooks:
157+
- id: datamodel-code-generator
158+
args: [--check]
159+
files: ^schemas/
160+
```
161+
162+
### With Profiles
163+
164+
For projects with multiple schemas using [named profiles](pyproject_toml.md#named-profiles):
165+
166+
```yaml title=".pre-commit-config.yaml"
167+
repos:
168+
- repo: https://github.com/koxudaxi/datamodel-code-generator
169+
rev: vX.Y.Z
170+
hooks:
171+
- id: datamodel-code-generator
172+
name: Check API models
173+
args: [--profile, api, --check]
174+
files: ^schemas/openapi/
175+
- id: datamodel-code-generator
176+
name: Check event models
177+
args: [--profile, events, --check]
178+
files: ^schemas/jsonschema/
179+
```
180+
181+
### Auto-regenerate Mode
182+
183+
This configuration automatically regenerates models when schema files change:
184+
185+
```yaml title=".pre-commit-config.yaml"
186+
repos:
187+
- repo: https://github.com/koxudaxi/datamodel-code-generator
188+
rev: vX.Y.Z
189+
hooks:
190+
- id: datamodel-code-generator
191+
files: ^schemas/
192+
```
193+
194+
!!! note "Installing the hook"
195+
Ensure `pre-commit` is installed, then install the hooks:
196+
197+
```bash
198+
pip install pre-commit
199+
pre-commit install
200+
```
201+
202+
---
203+
204+
## GitLab CI
205+
206+
```yaml title=".gitlab-ci.yml"
207+
check-generated-code:
208+
image: python:3.14
209+
script:
210+
- pip install datamodel-code-generator
211+
- datamodel-codegen --check
212+
rules:
213+
- changes:
214+
- schemas/**/*
215+
- src/models/**/*
216+
```
217+
218+
---
219+
220+
## Makefile Integration
221+
222+
Add targets to your Makefile for easy generation and checking:
223+
224+
```makefile title="Makefile"
225+
.PHONY: generate-models check-models
226+
227+
generate-models:
228+
datamodel-codegen
229+
230+
check-models:
231+
datamodel-codegen --check
232+
```
233+
234+
Then use in CI:
235+
236+
```yaml title=".github/workflows/ci.yml"
237+
- name: Check generated models
238+
run: make check-models
239+
```
240+
241+
For projects with multiple profiles:
242+
243+
```makefile title="Makefile"
244+
.PHONY: generate-all check-all
245+
246+
generate-all:
247+
datamodel-codegen --profile api
248+
datamodel-codegen --profile events
249+
250+
check-all:
251+
datamodel-codegen --profile api --check
252+
datamodel-codegen --profile events --check
253+
```
254+
255+
---
256+
257+
## Troubleshooting
258+
259+
### Check fails due to formatting differences
260+
261+
Ensure you're using the same formatters in CI as locally. Configure formatters in `pyproject.toml`:
262+
263+
```toml title="pyproject.toml"
264+
[tool.datamodel-codegen]
265+
formatters = ["ruff"]
266+
```
267+
268+
See [Formatting](formatting.md) for details.
269+
270+
**Related:** [`--formatters`](cli-reference/template-customization.md#formatters)
271+
272+
### Check fails due to timestamp
273+
274+
Always use `disable-timestamp = true` in `pyproject.toml`:
275+
276+
```toml title="pyproject.toml"
277+
[tool.datamodel-codegen]
278+
disable-timestamp = true
279+
```
280+
281+
**Related:** [`--disable-timestamp`](cli-reference/template-customization.md#disable-timestamp)
282+
283+
### Different Python versions produce different output
284+
285+
Some type annotations differ between Python versions. Pin the target version in `pyproject.toml` and ensure CI uses the same Python version as development:
286+
287+
```toml title="pyproject.toml"
288+
[tool.datamodel-codegen]
289+
target-python-version = "3.14"
290+
```
291+
292+
**Related:** [`--target-python-version`](cli-reference/model-customization.md#target-python-version)

‎docs/cli-reference/field-customization.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ Apply custom field and class name aliases from JSON file.
3434
The `--aliases` option allows renaming fields and classes via a JSON mapping file,
3535
providing fine-grained control over generated names independent of schema definitions.
3636

37+
**See also:** [Field Aliases](../aliases.md)
38+
3739
!!! tip "Usage"
3840

3941
```bash
@@ -386,7 +388,7 @@ The `--capitalize-enum-members` flag converts enum member names to
386388
UPPER_CASE format (e.g., `active` becomes `ACTIVE`), following Python
387389
naming conventions for constants.
388390

389-
**Related:** [`--snake-case-field`](field-customization.md#snake-case-field)
391+
**Aliases:** `--capitalise-enum-members` | **Related:** [`--snake-case-field`](field-customization.md#snake-case-field)
390392

391393
!!! tip "Usage"
392394

@@ -853,6 +855,8 @@ The `--field-constraints` flag generates Pydantic Field() definitions with
853855
validation constraints (min/max length, pattern, etc.) from the schema.
854856
Output differs between Pydantic v1 and v2 due to API changes.
855857

858+
**See also:** [Field Constraints](../field-constraints.md)
859+
856860
!!! tip "Usage"
857861

858862
```bash
@@ -1605,6 +1609,8 @@ names contain characters invalid in Python (like hyphens). Without this flag,
16051609
fields are renamed to Python-safe names with `Field(alias='original-name')`.
16061610
With this flag, only Python-safe names are used without aliases.
16071611

1612+
**See also:** [Field Aliases](../aliases.md)
1613+
16081614
!!! tip "Usage"
16091615

16101616
```bash

0 commit comments

Comments
 (0)