Geração Swagger/OpenAPI para Rust: biblioteca Utoipa

Geração Swagger/OpenAPI para Rust: Utoipa — ferramenta moderna para documentação automática

Ao desenvolver aplicações web em Rust, a documentação da API não é um luxo, mas uma necessidade. A biblioteca Utoipa (abreviação de "Utopia") oferece uma maneira poderosa e elegante de gerar especificações OpenAPI diretamente do código. Ela se integra com frameworks web populares como actix-web, axum, rocket e warp, e permite descrever endpoints, esquemas de dados e parâmetros usando atributos e macros.

Principais recursos do Utoipa

• Geração automática de OpenAPI 3.0/3.1 — sem escrever YAML/JSON manualmente.
• Suporte a múltiplos frameworks — actix-web, axum, rocket, warp.
• Integração com Swagger UI — componente embutido para visualização da documentação.
• Descrição aprofundada de esquemas — suporte a estruturas aninhadas, enumerações, campos opcionais.
• Macros para descrição rápida — #[utoipa::path], #[openapi].
• Validação de especificação — verificação da correção do documento gerado.

Instalação e configuração

Adicione as dependências no Cargo.toml. Como exemplo, escolheremos o framework actix-web:

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

Exemplo básico: criando uma API com documentação

Vamos considerar um CRUD simples para a entidade "Usuário". Começamos definindo o modelo de dados:

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

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

Agora descrevemos o endpoint de listagem de usuários usando a macro #[utoipa::path]:

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

#[utoipa::path(    get,    path = "/users",    responses(        (status = 200, description = "Lista de usuários", body = Vec<User>)    ))]#[get("/users")]async fn get_users() -> impl Responder {    let users = vec![        User { id: 1, username: "alice".into(), email: "alice@exemplo.com".into() },        User { id: 2, username: "bob".into(), email: "bob@exemplo.com".into() },    ];    HttpResponse::Ok().json(users)}

Montagem do documento OpenAPI e Swagger UI

Criamos uma estrutura para descrever toda a API:

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

// Na função main configuramos o Swagger UIuse 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}

Após iniciar a aplicação, a documentação estará disponível em http://localhost:8080/swagger-ui/.

Recursos avançados: esquemas aninhados e parâmetros

O Utoipa suporta tipos de dados complexos. Por exemplo, vamos adicionar um campo com estrutura aninhada:

#[derive(Serialize, Deserialize, ToSchema)]pub struct Address {    #[schema(example = "São Paulo")]    pub city: String,    #[schema(example = "Av. Paulista, 1000")]    pub street: String,}