tideway 0.7.17

A batteries-included Rust web framework built on Axum for building SaaS applications quickly
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! API Macro Example
//!
//! Demonstrates the `#[tideway::api]` macro for defining HTTP handlers
//! with automatic OpenAPI documentation generation.
//!
//! Run with: cargo run --example api_macro_example --features macros,openapi

use axum::{
    Json,
    extract::{Path, State},
};
use serde::{Deserialize, Serialize};
use tideway::{App, AppContext, ConfigBuilder, Result, RouteModule, api};
use uuid::Uuid;

/// User response type
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct UserResponse {
    pub id: Uuid,
    pub name: String,
    pub email: String,
}

/// Create user request
#[derive(Debug, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct CreateUserRequest {
    pub name: String,
    pub email: String,
}

/// Get a user by ID
///
/// Retrieves user information based on the provided UUID.
#[api(get, "/users/:id", tag = "users")]
async fn get_user(
    State(_ctx): State<AppContext>,
    Path(id): Path<Uuid>,
) -> Result<Json<UserResponse>> {
    // In a real app, this would query the database
    Ok(Json(UserResponse {
        id,
        name: "John Doe".to_string(),
        email: "john@example.com".to_string(),
    }))
}

/// Create a new user
#[api(post, "/users", tag = "users", summary = "Create a new user account")]
async fn create_user(
    State(_ctx): State<AppContext>,
    Json(req): Json<CreateUserRequest>,
) -> Result<Json<UserResponse>> {
    Ok(Json(UserResponse {
        id: Uuid::new_v4(),
        name: req.name,
        email: req.email,
    }))
}

/// List all users
#[api(get, "/users", tag = "users")]
async fn list_users(State(_ctx): State<AppContext>) -> Result<Json<Vec<UserResponse>>> {
    Ok(Json(vec![
        UserResponse {
            id: Uuid::new_v4(),
            name: "Alice".to_string(),
            email: "alice@example.com".to_string(),
        },
        UserResponse {
            id: Uuid::new_v4(),
            name: "Bob".to_string(),
            email: "bob@example.com".to_string(),
        },
    ]))
}

/// Health check endpoint (no tag specified - uses default)
#[api(get, "/health", skip_openapi = true)]
async fn health_check() -> &'static str {
    "OK"
}

// Define the route module
struct UsersModule;

impl RouteModule for UsersModule {
    fn routes(&self) -> axum::Router<AppContext> {
        use axum::routing::get;

        axum::Router::new()
            .route("/users", get(list_users).post(create_user))
            .route("/users/:id", get(get_user))
            .route("/health", get(health_check))
    }

    fn prefix(&self) -> Option<&str> {
        Some("/api")
    }
}

#[tokio::main]
async fn main() {
    tideway::init_tracing();

    let config = ConfigBuilder::new()
        .with_host("0.0.0.0")
        .with_port(3000)
        .from_env()
        .build()
        .expect("Failed to build config");

    let app = App::with_config(config).register_module(UsersModule);

    tracing::info!("API Macro Example running on http://0.0.0.0:3000");
    tracing::info!("Endpoints:");
    tracing::info!("  GET  /api/users");
    tracing::info!("  POST /api/users");
    tracing::info!("  GET  /api/users/:id");
    tracing::info!("  GET  /api/health");

    app.serve().await.unwrap();
}