Rust के लिए Swagger/OpenAPI जनरेशन: Utoipa लाइब्रेरी

Rust के लिए Swagger/OpenAPI जनरेशन: Utoipa — ऑटोमैटिक डॉक्यूमेंटेशन का आधुनिक टूल

Rust में वेब एप्लिकेशन डेवलप करते समय API डॉक्यूमेंटेशन कोई विलासिता नहीं, बल्कि एक आवश्यकता है। Utoipa लाइब्रेरी ("Utopia" का संक्षिप्त रूप) कोड से सीधे OpenAPI स्पेसिफिकेशन जनरेट करने का एक शक्तिशाली और सुरुचिपूर्ण तरीका प्रदान करती है। यह लोकप्रिय वेब फ्रेमवर्क जैसे actix-web, axum, rocket और warp के साथ एकीकृत होती है, और आपको एट्रीब्यूट और मैक्रोज़ के माध्यम से एंडपॉइंट, डेटा स्कीमा और पैरामीटर को परिभाषित करने की अनुमति देती है।

Utoipa की मुख्य विशेषताएं

• ऑटोमैटिक OpenAPI 3.0/3.1 जनरेशन — मैन्युअल रूप से YAML/JSON लिखने की जरूरत नहीं।
• कई फ्रेमवर्क का सपोर्ट — actix-web, axum, rocket, warp।
• Swagger UI के साथ एकीकरण — डॉक्यूमेंटेशन विज़ुअलाइज़ेशन के लिए बिल्ट-इन कंपोनेंट।
• गहन स्कीमा विवरण — नेस्टेड स्ट्रक्चर, एनुम, ऑप्शनल फील्ड का सपोर्ट।
• त्वरित विवरण के लिए मैक्रोज़ — #[utoipa::path], #[openapi]।
• स्पेसिफिकेशन वैलिडेशन — जनरेटेड डॉक्यूमेंट की सटीकता की जांच।

इंस्टॉलेशन और सेटअप

Cargo.toml में डिपेंडेंसी जोड़ें। उदाहरण के लिए, actix-web फ्रेमवर्क चुनें:

[dependencies]
utoipa = "4"
utoipa-swagger-ui = { version = "4", features = ["actix-web"] }
actix-web = "4"
serde = { version = "1", features = ["derive"] }

बेसिक उदाहरण: डॉक्यूमेंटेशन के साथ API बनाना

"यूज़र" एंटिटी के लिए एक सरल CRUD देखते हैं। डेटा मॉडल को परिभाषित करके शुरू करें:

use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

#[derive(Serialize, Deserialize, ToSchema)]
pub struct User {
    #[schema(example = "1")]
    pub id: i32,
    #[schema(example = "john_doe")]
    pub username: String,
    #[schema(example = "john@example.com")]
    pub email: String,
}

अब #[utoipa::path] मैक्रो का उपयोग करके यूज़रों की सूची प्राप्त करने वाले एंडपॉइंट का वर्णन करें:

use actix_web::{get, web, HttpResponse, Responder};
use utoipa::OpenApi;

#[utoipa::path(
    get,
    path = "/users",
    responses(
        (status = 200, description = "यूज़रों की सूची", body = Vec<User>)
    )
)]
#[get("/users")]
async fn get_users() -> impl Responder {
    let users = vec![
        User { id: 1, username: "alice".into(), email: "alice@example.com".into() },
        User { id: 2, username: "bob".into(), email: "bob@example.com".into() },
    ];
    HttpResponse::Ok().json(users)
}

OpenAPI डॉक्यूमेंट और Swagger UI तैयार करना

पूरे API का वर्णन करने के लिए एक स्ट्रक्चर बनाएं:

#[derive(OpenApi)]
#[openapi(
    paths(get_users),
    components(schemas(User))
)]
pub struct ApiDoc;

// main फंक्शन में Swagger UI सेटअप करें
use utoipa_swagger_ui::SwaggerUi;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    use actix_web::App;

    HttpServer::new(|| {
        App::new()
            .service(get_users)
            .service(
                SwaggerUi::new("/swagger-ui/{_:.*}")
                    .url("/api-docs/openapi.json", ApiDoc::openapi())
            )
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

एप्लिकेशन चलाने के बाद, डॉक्यूमेंटेशन http://localhost:8080/swagger-ui/ पर उपलब्ध होगा।

उन्नत सुविधाएं: नेस्टेड स्कीमा और पैरामीटर

Utoipa जटिल डेटा प्रकारों को सपोर्ट करता है। उदाहरण के लिए, नेस्टेड स्ट्रक्चर वाला फील्ड जोड़ें:

#[derive(Serialize, Deserialize, ToSchema)]
pub struct Address {
    #[schema(example = "मुंबई")]
    pub city: String,
    #[schema(example = "गांधी रोड, घर नं. 5")]
    pub street: String,
}

#[derive(Serialize, Deserialize, ToSchema)]
pub struct UserWithAddress {
    pub id: i32,
    pub us