Génération Swagger/OpenAPI pour Rust : Utoipa et Aide

Génération Swagger/OpenAPI pour Rust : Utoipa et Aide

Dans le développement web moderne en Rust, créer une API documentée n'est pas un luxe, mais une nécessité. Swagger (OpenAPI) permet de générer automatiquement une documentation interactive, des SDK clients et des consoles de test. Dans l'écosystème Rust, deux outils occupent une position de leader : Utoipa (basé sur les macros) et Aide (axé sur la typage et le contrôle manuel). Examinons-les en détail.

Utoipa — des macros pour OpenAPI 3.0

Utoipa est une bibliothèque qui utilise des attributs-macros (#[utoipa::path]) pour générer automatiquement une spécification OpenAPI. Elle s'intègre étroitement avec les frameworks populaires : Actix-web, Axum, Rocket, Warp.

Caractéristiques :

• Prise en charge complète d'OpenAPI 3.0 (paths, components, security schemes).
• Extraction automatique des types à partir des structures Rust (avec #[derive(ToSchema)]).
• Génération d'un fichier JSON/YAML pour Swagger UI.
• Prise en charge native de actix-web (via utoipa-swagger-ui).
• Faible seuil d'entrée — il suffit d'ajouter des macros.

Exemple avec Actix-web :

use actix_web::{get, web, App, HttpResponse, HttpServer, Responder};use serde::{Deserialize, Serialize};use utoipa::{OpenApi, ToSchema};use utoipa_swagger_ui::SwaggerUi;

#[derive(Serialize, Deserialize, ToSchema)]struct User {    id: u32,    name: String,}

#[utoipa::path(    get,    path = "/users/{id}",    responses(        (status = 200, description = "User found", body = User),        (status = 404, description = "User not found")    ),    params(        ("id" = u32, Path, description = "User ID")    ))]#[get("/users/{id}")]async fn get_user(id: web::Path<u32>) -> impl Responder {    HttpResponse::Ok().json(User {        id: id.into_inner(),        name: "Alice".into(),    })}

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

#[actix_web::main]async fn main() -> std::io::Result<()> {    HttpServer::new(|| {        App::new()            .service(get_user)            .service(                SwaggerUi::new("/swagger-ui/{_:.*}")                    .url("/api-doc/openapi.json", ApiDoc::openapi()),            )    })    .bind("127.0.0.1:8080")?    .run()    .await}

Aide — contrôle et typage

Aide (anciennement paperclip) propose une approche différente : vous décrivez explicitement la spécification via des structures et des fonctions, plutôt qu'avec des macros. Cela offre plus de contrôle, mais nécessite plus de code. La bibliothèque prend en charge Axum et Actix-web.

Caractéristiques :

• Typage pur — toutes les descriptions sont définies via des enum et des struct.
• Validation intégrée des schémas lors de la génération.
• Prise en charge des modèles imbriqués et des compositions (allOf, oneOf).
• Flexibilité : vous pouvez redéfinir n'importe quel aspect de la spécification.

Exemple avec Axum :

use aide::{axum::ApiRouter, openapi::OpenApi};use axum::{routing::get, Json, Router};use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]struct Pet {    id: u32,    name: String,}

async fn list_pets() -> Json<Vec<Pet>> {    Json(vec![Pet {        id: 1,        name: "Rex".into(),    }])}

async fn api_docs() -> Json<OpenApi> {    let mut api = OpenApi::default();    api.info.title = "Pet Store API".into();    api.info.version = "1.0.0".into();    Json(api)}

#[tokio::main]async fn main() {    let app = ApiRouter::new()        .route("/pets", get(list_pets))        .route("/api-doc", get(api_docs));

    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())        .serve(app.into_make_service())        .await        .unwrap();}