notes

openapi-guide.md (7230B)

---

 # Open API guide
 
 # Bridging the Type Gap: End-to-End Type Safety with Axum, Aide, and Orval
 
 One of the most frustrating experiences in full-stack development is the "silent
 failure": you change a field name in your Rust backend, everything compiles
 perfectly, but your frontend suddenly starts receiving `undefined` and crashing
 in production.
 
 To solve this, we need a **Single Source of Truth**. Instead of manually
 maintaining TypeScript interfaces that mirror your Rust structs, you can
 automate the entire pipeline:
 
 **Rust Models $\rightarrow$ OpenAPI Spec $\rightarrow$ TypeScript Axios Client**
 
 In this guide, we'll use **`aide`** to generate an OpenAPI specification
 directly from our Axum types and **`orval`** to transform that spec into a
 type-safe Axios client.
 
 ---
 
 ## Part 1: The Backend (Rust + Axum + Aide)
 
 Traditionally, writing an OpenAPI (Swagger) spec means writing a giant YAML file
 by hand. **`aide`** eliminates this by leveraging Rust's type system to generate
 the spec at runtime.
 
 ### 1. Dependencies
 
 Add these to your `Cargo.toml`:
 
 ```toml
 [dependencies]
 axum = "0.7" # Ensure version compatibility with aide
 aide = { version = "0.15", features = ["axum"] }
 schemars = "0.8" # Required for generating JSON schemas from structs
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 tokio = { version = "1.0", features = ["full"] }
 ```
 
 ### 2. The Implementation
 
 The core idea is to replace Axum's standard `Router` with `ApiRouter` and ensure
 your data models implement `JsonSchema`.
 
 ```rust
 use aide::{
     axum::{routing::{get, post}, ApiRouter, IntoApiResponse},
     openapi::{Info, OpenApi},
 };
 use axum::{Extension, Json};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 // 1. All models must derive JsonSchema to be visible in the OpenAPI spec
 #[derive(Deserialize, Serialize, JsonSchema)]
 struct User {
     id: u64,
     username: String,
     email: String,
 }
 
 // 2. Handlers must return types that implement IntoApiResponse
 async fn create_user(Json(user): Json<User>) -> impl IntoApiResponse {
     // In a real app, you'd save to DB here
     Json(user)
 }
 
 async fn serve_api(Extension(api): Extension<OpenApi>) -> impl IntoApiResponse {
     Json(api)
 }
 
 #[tokio::main]
 async fn main() {
     // Define the OpenApi metadata
     let mut api = OpenApi {
         info: Info {
             title: "My Awesome API".to_string(),
             version: "1.0.0".to_string(),
             ..Info::default()
         },
         ..OpenApi::default()
     };
 
     // Use ApiRouter instead of Router
     let app = ApiRouter::new()
         // Use api_route to explicitly include the route in the documentation
         .api_route("/users", post(create_user))
         // Standard route for the JSON spec itself
         .route("/api.json", get(serve_api));
 
     let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
 
     axum::serve(
         listener,
         app
             .finish_api(&mut api) // Finalize the spec generation
             .layer(Extension(api)) // Inject the spec into the handlers
             .into_make_service(),
     )
     .await
     .unwrap();
 }
 ```
 
 ### How it works:
 
 - **`JsonSchema`**: The `schemars` crate analyzes your Rust struct at
   compile-time and allows `aide` to describe it in JSON format.
 - **`ApiRouter`**: This acts as a wrapper. Whenever you call `.api_route()`,
   `aide` records the types of the request and response.
 - **`/api.json`**: We expose the generated `OpenApi` struct as a JSON endpoint.
   This is the bridge to our frontend.
 
 ---
 
 ## Part 2: The Frontend (TypeScript + Orval)
 
 Now that our backend is shouting its structure via `/api.json`, we use **Orval**
 to listen. Orval reads the OpenAPI spec and generates an entire API
 client—including request functions and TypeScript types—so you never have to
 write a `fetch` or `axios` call manually.
 
 ### 1. Install Dependencies
 
 ```bash
 npm install axios
 npm install -D orval
 ```
 
 ### 2. Configure Orval
 
 Create an `orval.config.js` file in your project root:
 
 ```javascript
 module.exports = {
   "my-api": {
     input: "http://localhost:3000/api.json", // The URL from our Rust app
     output: {
       target: "./src/api/generated.ts",
       client: "axios",
       override: {
         axios: {
           useBaseUrl: true,
           baseURL: "http://localhost:3000",
         },
       },
     },
   },
 };
 ```
 
 ### 3. Generate the Client
 
 Run the generator:
 
 ```bash
 npx orval
 ```
 
 Orval will now create `src/api/generated.ts`. Inside, you'll find:
 
 1. **TypeScript Interfaces**: Exactly matching the Rust `User` struct.
 2. **Request Functions**: A function like `createUser` that takes a `User`
    object and returns a Promise of a `User`.
 
 ### 4. Use it in your Frontend (Svelte/React/Vue)
 
 Now, your API calls are fully type-safe:
 
 ```typescript
 import { createUser } from "./api/generated";
 
 async function handleSignUp(formData: any) {
   try {
     // TypeScript will error here if formData doesn't match the Rust User struct!
     const user = await createUser({
       id: 1,
       username: "rust_lover",
       email: "hello@rust.rs",
     });
     console.log("User created:", user.username);
   } catch (e) {
     console.error("API Error", e);
   }
 }
 ```
 
 ---
 
 ## Part 3: Using CI to Keep the Spec Up to Date
 
 To make this architecture truly production-ready, you shouldn't rely on manually
 running `npx orval` every time you change a field in Rust. Instead, you can
 integrate this into your **CI/CD pipeline**.
 
 ### The "Golden File" Strategy
 
 Since `aide` generates the specification at runtime, the most robust way to
 handle CI is to treat the OpenAPI JSON as a versioned artifact (a "Golden
 File").
 
 #### 1. Export the Spec during Backend CI
 
 Create a Rust test in your backend that runs the `ApiRouter`, generates the
 `OpenApi` object, and writes it to a file:
 
 ```rust
 #[tokio::test]
 async fn export_openapi_spec() {
     let mut api = OpenApi::default();
     let app = ApiRouter::new().api_route("/users", post(create_user));
     
     app.finish_api(&mut api);
     
     let json = serde_json::to_string_pretty(&api).unwrap();
     std::fs::write("openapi.json", json).expect("Unable to write spec file");
 }
 ```
 
 #### 2. The CI Pipeline (GitHub Actions Example)
 
 Set up a workflow that triggers the frontend whenever the `openapi.json`
 changes:
 
 ```yaml
 name: API Type Sync
 on:
   push:
     paths:
       - "backend/**"
 
 jobs:
   sync-types:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Export OpenAPI Spec
         run: |
           cargo test --test export_openapi_spec
 
       - name: Generate Frontend Client
         run: |
           cd frontend
           npm install
           npx orval
 
       - name: Type Check Frontend
         run: |
           cd frontend
           npm run type-check # Run 'tsc' to see if API changes broke the UI
 ```
 
 ### Summary of the Automated Flow
 
 1. **Developer** pushes a change to a Rust struct.
 2. **CI** runs a test to generate the latest `openapi.json`.
 3. **CI** runs Orval to update the TypeScript Axios client.
 4. **CI** runs the TypeScript compiler (`tsc`). If the Rust change broke a
    frontend component, the **build fails** before the code ever reaches
    production.