71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
# Codegen — Generate Models & Routes From Your Spec
|
||
|
||
> **TL;DR** — point `openapi-first codegen` at your spec and get `models` + `routes` scaffolds you can bind with one line. The codegen output is deterministic, and it's a *starting point* — not a maintained artifact.
|
||
|
||
---
|
||
|
||
## 🧭 1. Why Celebrate Codegen?
|
||
|
||
Two pain points kill OpenAPI projects:
|
||
|
||
1. **The "write the spec, then write the same thing as Pydantic models" step** — exactly where server/client param types drift (your route says `item_id: int`, your client sends a string…).
|
||
2. **Writing the docs/spec catalog by hand**, once you have more than a handful of operations.
|
||
|
||
Codegen collapses both. One command, one source file, same generated shapes everywhere.
|
||
|
||
---
|
||
|
||
## 🚀 2. Model Generation
|
||
|
||
```bash
|
||
openapi-first codegen models --module my_project.models --input openapi.yaml
|
||
```
|
||
|
||
The generated model module mirrors the spec's `components.schemas` **by name**:
|
||
|
||
| Spec | Generated |
|
||
|------|-----------|
|
||
| `components.schemas.User` | `class User(BaseModel)` |
|
||
| `components.schemas.Item` | `class Item(BaseModel)` |
|
||
| every `$ref` (schema) | a `type: ClassVar` alias ✓ |
|
||
| `required + type` from schema | Pydantic `Field(...)` / type hints ✓ |
|
||
|
||
**Never hand-edit those files.** If the spec changes, regenerate — just like you'd re-run `cargo build` after editing `Cargo.toml`.
|
||
|
||
### Why constructor-time validation still applies
|
||
|
||
Codegen doesn't change the design: the generated models are plain Pydantic, and the **client/server still validate against the spec** at startup. Codegen is a *convenience accelerator* on top of the fail-fast guarantees in [04 – Design](../04_design.md) and [06 – Error Handling](../06_error_handling.md).
|
||
|
||
---
|
||
|
||
## 🔁 3. Route Generation / Verification
|
||
|
||
```bash
|
||
# dry-run verification against your routes module
|
||
openapi-first codegen routes --module my_routes --input openapi.yaml --check
|
||
|
||
# scaffold an operation skeleton (generates the handler with a TODO)
|
||
openapi-first codegen routes --module my_routes --input openapi.yaml
|
||
```
|
||
|
||
Why bother? Because `bind_routes` (in [02 – Components](../02_components.md)) needs an `operationId` → handler **exactly** matching the spec. Codegen guarantees you never type a handler name wrong — it wears the same `operationId` as the spec says.
|
||
|
||
> **Note:** `codegen` is build-time tooling. It does **not** run at runtime, and templates (the Bake-your-stuff section of [02 – Templates](02_templates.md)) make scaffolding a server out-of-the-box even simpler for greenfield projects.
|
||
|
||
---
|
||
|
||
## 🧪 4. Idempotent Output
|
||
|
||
Generated output is deterministic w.r.t. the spec:
|
||
- Same spec → byte-identical files (unless you hand-edit — you won't)
|
||
- Ordering follows spec declaration order
|
||
- No timestamps, no machine names, no hidden randomness
|
||
|
||
That determinism is what lets you `git diff` after a spec change and see **exactly** what moved.
|
||
|
||
---
|
||
|
||
## 🧩 Related
|
||
|
||
- [01 – Overview](../01_overview.md) · [02 – Templates](02_templates.md) · [03 – Client](03_client.md) · [04 – Design](../04_design.md) · [07 – Testing](../07_testing.md)
|