You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**cdd-rust** creates a symbiotic link between your **Database**, **Rust Code**, and **OpenAPI Specifications**. Unlike traditional generators that overwrite files or hide code in "generated" directories, `cdd-rust` uses advanced AST parsing (`ra_ap_syntax`) to surgically patch your *existing* source files, strictly typed handlers, and integration tests.
9
+
**cdd-rust** creates a symbiotic link between your **Database**, **Rust Code**, and **OpenAPI Specifications**. Unlike traditional generators that overwrite files or hide code in "generated" directories, `cdd-rust` uses advanced AST parsing (`ra_ap_syntax`) to surgically patch your *existing* source files, strictly typed handlers, and integration tests.
10
10
11
-
It supports two distinct workflows:
12
-
1.**Scaffold | Patch (OpenAPI ➔ Rust):** Generate/update Actix handlers, routes, and Diesel models from OpenAPI.
13
-
2.**Reflect & Sync (Rust ➔ OpenAPI):** Generate OpenAPI specifications from your actual source code.
11
+
Uniquely, `cdd-rust` is built on a **strategy-based architecture**. While the default implementation provides a robust **Actix Web + Diesel** workflow, the core logic is decoupled into strategies and mappers, making it extensible to other ecosystems (e.g., Axum, SQLx) in the future.
12
+
13
+
It supports two distinct workflows:
14
+
1.**Scaffold | Patch (OpenAPI ➔ Rust):** Generate/update handlers, routes, and models via `BackendStrategy`.
15
+
2.**Reflect & Sync (Rust ➔ OpenAPI):** Generate OpenAPI specifications from your source code and DB via `ModelMapper`.
Diesel("<strong>Diesel Model (Rust)</strong><br/>#[derive(ToSchema)]<br/>struct User {<br/> id: Uuid,<br/> email: String<br/>}"):::green
53
+
Diesel("<strong>Data Model (Rust)</strong><br/>#[derive(ToSchema)]<br/>struct User {<br/> id: Uuid,<br/> email: String<br/>}"):::green
The internal architecture separates the core AST/OpenAPI parsing logic from the target code generation. This allows the tool to support multiple web frameworks and ORMs through the `BackendStrategy` and `ModelMapper` traits.
Stop manually writing repetitive handler signatures. `cdd-rust` reads your spec and generates strictly typed code based on the active `BackendStrategy`.
135
+
***Handler Scaffolding:** Transforms OpenAPI paths into `async fn` signatures with correct extractors (currently `ActixStrategy` defaults):
72
136
* Path variables ➔ `web::Path<Uuid>`
73
137
* Query strings ➔ `web::Query<Value>`
74
138
* Request bodies ➔ `web::Json<T>`
75
-
***Route Registration:** Surgically injects `cfg.service(...)` calls into your `routes.rs` configuration using AST analysis, preserving existing logic.
76
-
***Non-Destructive Patching:** Uses [`ra_ap_syntax`](https://docs.rs/ra_ap_syntax/) (part of official [rust-lang/rust-analyzer](https://github.com/rust-lang/rust-analyzer)) to edit files safely. It respects your manual comments and formatting.
Keep your documentation alive. Your Rust code *is* the spec.
80
-
***Database Sync:**Wraps `dsync` to generate Rust structs directly from your Postgres `schema.rs`.
81
-
***Attribute Injection:** Automatically parses structs and injects `#[derive(ToSchema)]` and `#[serde(...)]` attributes.
82
-
***Type Mapping:** Maps Rust types (`Uuid`, `chrono::NaiveDateTime`) back to OpenAPI formats automatically.
144
+
***Model Mapper Trait:**Extracts DB Schemas via `ModelMapper` (currently `DieselMapper` wrapping `dsync`) to generate/update Rust structs.
145
+
***Attribute Injection:** Automatically parses structs and injects `#[derive(ToSchema)]` and `#[serde(...)]` attributes to make models OpenAPI-compatible.
146
+
***Type Mapping:** Maps Rust types (`Uuid`, `chrono::NaiveDateTime`, `Decimal`) back to OpenAPI formats automatically using the `TypeMapper` module.
83
147
84
148
### 3. Contract Safety (`test-gen`)
85
-
Ensure your implementation actually matches the spec.
149
+
Ensure your implementation actually matches the spec using the same strategies used for code generation.
86
150
***Test Generation:** Generates `tests/api_contracts.rs` based on your `openapi.yaml`.
87
-
***Smart Mocking:** Automatically fills request parameters with valid dummy data (e.g., UUIDs for ID fields, ISO strings for Dates).
88
-
***Validation:** Verifies that your API responses align with the JSON Schema defined in your spec.
151
+
***Smart Mocking:** Automatically fills request parameters with valid dummy data based on type signatures.
152
+
***Validation:** Verifies that API responses align with the JSON Schema defined in your spec.
89
153
90
-
---
154
+
---
91
155
92
156
## 📦 Command Usage
93
157
94
158
### 1. The Sync Pipeline
95
159
**DB ➔ Rust Models ➔ OpenAPI Attributes**
96
-
Synchronizes your database schema to your Rust structs and ensures they are ready for OpenAPI generation.
160
+
Synchronizes your database schema to your Rust structs using the configured `ModelMapper`.
97
161
98
162
```bash
99
-
cargo run -p cdd-cli -- sync \
100
-
--schema-path web/src/schema.rs \
163
+
cargo run -p cdd-cli -- sync \
164
+
--schema-path web/src/schema.rs \
101
165
--model-dir web/src/models
102
166
```
103
167
104
168
### 2. The Test Pipeline
105
169
**OpenAPI ➔ Integration Tests**
106
-
Generates a test suite that treats your app as a black box.
170
+
Generates a test suite via `BackendStrategy` (default: Actix) that treats your app as a black box.
107
171
108
172
```bash
109
-
cargo run -p cdd-cli -- test-gen \
110
-
--openapi-path docs/openapi.yaml \
111
-
--output-path web/tests/api_contracts.rs \
173
+
cargo run -p cdd-cli -- test-gen \
174
+
--openapi-path docs/openapi.yaml \
175
+
--output-path web/tests/api_contracts.rs \
112
176
--app-factory crate::create_app
113
177
```
114
178
115
-
---
179
+
---
116
180
117
181
## 🛠 Project Structure
118
182
119
-
***`core/`**: The engine. Contains AST parsers, OpenAPI parsers, and the diff/patch logic.
183
+
***`core/`**: The engine. Contains AST parsers, strategies, and the diff/patch logic.
184
+
*`strategies.rs`: Defines `BackendStrategy` trait and `ActixStrategy`.
***`cli/`**: The workflow runner. Use this to run `sync` or `test-gen`.
186
+
*`oas.rs`: Parses OpenAPI YAML into Intermediate Representations.
187
+
*`handlers/routes/contract_test`: Functional modules utilizing strategies to generate code.
188
+
***`cli/`**: The workflow runner. Wires up specific strategies to commands.
189
+
*`generator.rs`: Defines `ModelMapper` and `DieselMapper`.
190
+
*`main.rs`: Dependency injection root.
124
191
***`web/`**: Reference implementation. An Actix Web + Diesel project demonstrating the generated code in action.
125
192
126
193
## 🎨 Design Principles
127
194
128
195
***No Magic Folders:** We generate code you can read, debug, and commit.
129
196
***Lossless Patching:** We edit your source files without breaking your style.
197
+
***Pluggable Backend:** Core logic is decoupled from specific frameworks (Actix, Axum, etc.).
130
198
***Type Safety:**`Uuid`, `chrono`, and `rust_decimal` are first-class citizens.
131
-
***100% Coverage:** The toolchain itself enforces strict documentation and test coverage.
132
199
133
-
---
200
+
---
134
201
135
202
## Developer guide
136
203
137
204
Install the latest version of [Rust](https://www.rust-lang.org). We tend to use nightly versions. [CLI tool for installing Rust](https://rustup.rs).
138
205
139
206
We use [rust-clippy](https://github.com/rust-lang-nursery/rust-clippy) linters to improve code quality.
140
207
141
-
There are plenty of [IDEs](https://areweideyet.com) and other [Rust development tools to consider](https://github.com/rust-unofficial/awesome-rust#development-tools).
0 commit comments