Geração Swagger/OpenAPI para Rust: Utoipa e Aide

No desenvolvimento web moderno com Rust, criar uma API documentada não é um luxo, mas uma necessidade. Swagger (OpenAPI) permite gerar automaticamente documentação interativa, SDKs de cliente e consoles de teste. No ecossistema Rust, duas ferramentas ocupam posições de destaque: Utoipa (baseada em macros) e Aide (com foco em tipagem e controle manual). Vamos analisá-las em detalhes.

Utoipa — macros para OpenAPI 3.0

Utoipa é uma biblioteca que usa macros de atributos (#[utoipa::path]) para gerar automaticamente a especificação OpenAPI. Ela se integra fortemente com frameworks populares: Actix-web, Axum, Rocket, Warp.

Características:

Suporte completo ao OpenAPI 3.0 (paths, components, security schemes).
Extração automática de tipos de estruturas Rust (com #[derive(ToSchema)]).
Geração de arquivo JSON/YAML para Swagger UI.
Suporte nativo a actix-web (através de utoipa-swagger-ui).
Baixa barreira de entrada — basta adicionar as macros.

Exemplo com 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 — controle e tipagem

Aide (anteriormente paperclip) oferece uma abordagem diferente: você descreve explicitamente a especificação através de estruturas e funções, em vez de macros. Isso proporciona mais controle, mas requer mais código. A biblioteca suporta Axum e Actix-web.

Características:

Tipagem pura — todas as descrições são definidas via enum e struct.
Validação de esquemas embutida durante a geração.
Suporte a modelos aninhados e composições (allOf, oneOf).
Flexibilidade: é possível sobrescrever qualquer aspecto da especificação.

Exemplo com 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();}