// That's it. Swagger UI at /docs, OpenAPI at openapi.json let app = vespera!(openapi = "openapi.json", docs_url = "/docs");

use axum::{Json, Path}; use serde::{Deserialize, Serialize}; use vespera::Schema; #[derive(Serialize, Deserialize, Schema)] pub struct User { pub id: u32, pub name: String, } /// Get user by ID #[vespera::route(get, path = "/{id}", tags = ["users"])] pub async fn get_user(Path(id): Path<u32>) -> Json<User> { Json(User { id, name: "Alice".into() }) } /// Create a new user #[vespera::route(post, tags = ["users"])] pub async fn create_user(Json(user): Json<User>) -> Json<User> { Json(user) }

use vespera::vespera; #[tokio::main] async fn main() { let app = vespera!( openapi = "openapi.json", title = "My API", docs_url = "/docs" ); let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); println!("Swagger UI: http://localhost:3000/docs"); axum::serve(listener, app).await.unwrap(); }

// GET /users (default method) #[vespera::route] pub async fn list_users() -> Json<Vec<User>> { ... } // POST /users #[vespera::route(post)] pub async fn create_user(Json(user): Json<User>) -> Json<User> { ... } // GET /users/{id} #[vespera::route(get, path = "/{id}")] pub async fn get_user(Path(id): Path<u32>) -> Json<User> { ... } // Full options #[vespera::route(put, path = "/{id}", tags = ["users"], description = "Update user")] pub async fn update_user(...) -> ... { ... }

#[derive(Serialize, Deserialize, vespera::Schema)] #[serde(rename_all = "camelCase")] // Serde attributes are respected pub struct CreateUserRequest { pub user_name: String, // → "userName" in OpenAPI pub email: String, #[serde(default)] pub bio: Option<String>, // Optional field }

use vespera::multipart::{FieldData, TypedMultipart}; use vespera::{Multipart, Schema}; use tempfile::NamedTempFile; #[derive(Multipart, Schema)] pub struct CreateUploadRequest { pub name: String, #[form_data(limit = "10MiB")] pub file: Option<FieldData<NamedTempFile>>, } #[vespera::route(post, tags = ["uploads"])] pub async fn create_upload( TypedMultipart(req): TypedMultipart<CreateUploadRequest>, ) -> Json<UploadResponse> { ... }

use axum::extract::Multipart; #[vespera::route(post, tags = ["uploads"])] pub async fn upload(mut multipart: Multipart) -> Json<UploadResponse> { while let Some(field) = multipart.next_field().await.unwrap() { let name = field.name().unwrap_or("unknown").to_string(); let data = field.bytes().await.unwrap(); // Process each field dynamically... } Json(UploadResponse { success: true }) }

#[derive(Serialize, Schema)] pub struct ApiError { pub message: String, } #[vespera::route(get, path = "/{id}")] pub async fn get_user(Path(id): Path<u32>) -> Result<Json<User>, (StatusCode, Json<ApiError>)> { if id == 0 { return Err((StatusCode::NOT_FOUND, Json(ApiError { message: "Not found".into() }))); } Ok(Json(User { id, name: "Alice".into() })) }

let app = vespera!( dir = "routes", // Route folder (default: "routes") openapi = "openapi.json", // Output path (writes file at compile time) title = "My API", // OpenAPI info.title version = "1.0.0", // OpenAPI info.version (default: CARGO_PKG_VERSION) docs_url = "/docs", // Swagger UI endpoint redoc_url = "/redoc", // ReDoc endpoint servers = [ // OpenAPI servers { url = "https://api.example.com", description = "Production" }, { url = "http://localhost:3000", description = "Development" } ], merge = [crate1::App1, crate2::App2] // Merge child vespera apps );

// Basic usage (scans "routes" folder by default) vespera::export_app!(MyApp); // Custom directory vespera::export_app!(MyApp, dir = "api");

use vespera::schema_type; // Pick specific fields only schema_type!(CreateUserRequest from crate::models::user::Model, pick = ["name", "email"]); // Omit specific fields  schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]); // Add new fields schema_type!(UpdateUserRequest from crate::models::user::Model, pick = ["name"], add = [("id": i32)]);

// In src/models/user.rs pub struct Model { pub id: i32, pub name: String, pub email: String, } // Simple `Model` path works when using `name` parameter vespera::schema_type!(Schema from Model, name = "UserSchema");

// In src/routes/users.rs - references src/models/user.rs schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]);

schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]); // Now you can do: let model: Model = db.find_user(id).await?; Json(model.into()) // Automatic conversion!

// All fields become Option<T> schema_type!(UserPatch from User, partial); // Only specific fields become Option<T> schema_type!(UserPatch from User, partial = ["name", "email"]);

// Convert field names to camelCase in JSON schema_type!(UserDTO from User, rename_all = "camelCase"); // Available: "camelCase", "snake_case", "PascalCase", "SCREAMING_SNAKE_CASE", etc.

#[derive(DeriveEntityModel)] #[sea_orm(table_name = "posts")] pub struct Model { #[sea_orm(primary_key)] // ← has default (auto-increment) pub id: i32, pub title: String, pub content: String, #[sea_orm(default_value = "NOW()")] // ← has default (SQL function) pub created_at: DateTimeWithTimeZone, } // Omits `id` (primary_key) and `created_at` (default_value) automatically schema_type!(CreatePostRequest from crate::models::post::Model, omit_default); // Generated struct only has: title, content

// omit_default + add extra fields schema_type!(CreateItemRequest from Model, omit_default, add = [("tags": Vec<String>)]);

use sea_orm::entity::prelude::*; #[derive(Clone, Debug, DeriveEntityModel)] #[sea_orm(table_name = "memos")] pub struct Model { #[sea_orm(primary_key)] pub id: i32, pub title: String, pub user_id: i32, pub user: BelongsTo<super::user::Entity>, // → Option<Box<UserSchema>> pub comments: HasMany<super::comment::Entity>, // → Vec<CommentSchema> } // Generates Schema with proper relation types vespera::schema_type!(Schema from Model, name = "MemoSchema");

#[derive(vespera::Multipart, vespera::Schema)] pub struct CreateUploadRequest { pub name: String, #[form_data(limit = "10MiB")] pub file: Option<FieldData<NamedTempFile>>, pub description: Option<String>, } // Generates a Multipart struct (no serde derives), all fields Optional schema_type!(PatchUploadRequest from CreateUploadRequest, multipart, partial, omit = ["file"]);

use vespera::{Schema, schema}; #[derive(Schema)] pub struct User { pub id: i32, pub name: String, pub password: String, } // Full schema let full: vespera::schema::Schema = schema!(User); // With fields omitted let safe: vespera::schema::Schema = schema!(User, omit = ["password"]); // With only specified fields let summary: vespera::schema::Schema = schema!(User, pick = ["id", "name"]);

// src/cron/cleanup.rs, src/tasks.rs, or even src/routes/users.rs — anywhere works #[vespera::cron("1/10 * * * * *")] pub async fn cleanup_sessions() { println!("Running cleanup every 10 seconds"); } #[vespera::cron("0 0 * * * *")] pub async fn hourly_report() { println!("Running hourly report"); }

// No cron-specific config — just works let app = vespera!(docs_url = "/docs");

let app = vespera!(docs_url = "/docs") .with_state(AppState { db: pool });

let app = vespera!(docs_url = "/docs") .layer(CorsLayer::permissive()) .layer(TraceLayer::new_for_http());

let app = vespera!( openapi = ["openapi.json", "docs/api-spec.json"] );

// Scans src/api/ instead of src/routes/ let app = vespera!("api"); // Or explicitly let app = vespera!(dir = "api");

// src/lib.rs mod routes; // Export app for merging (dir defaults to "routes") vespera::export_app!(ThirdApp); // Or with custom directory // vespera::export_app!(ThirdApp, dir = "api");

// src/main.rs use vespera::vespera; let app = vespera!( openapi = "openapi.json", docs_url = "/docs", merge = [third::ThirdApp] // Merges router AND OpenAPI spec ) .with_state(app_state);