Rust Utoipa

Utoipa - OpenAPI Documentation for Rust

Auto-generate OpenAPI 3.1 specs from Rust code using derive macros. Current version: utoipa 5.4.0.

Quick Start

Add to Cargo.toml:

[dependencies]
utoipa = { version = "5", features = ["axum_extras"] }
utoipa-swagger-ui = { version = "9", features = ["axum"] }

1. Define a Schema

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

/// A pet in the store.
#[derive(Serialize, Deserialize, ToSchema)]
struct Pet {
    id: u64,
    #[schema(example = "Fluffy", min_length = 1, max_length = 100)]
    name: String,
    #[schema(minimum = 0, maximum = 30)]
    age: Option<i32>,
}

2. Document an Endpoint

/// Get pet by ID
///
/// Returns a single pet by its database ID.
#[utoipa::path(
    get,
    path = "/pets/{id}",
    params(
        ("id" = u64, Path, description = "Pet database ID"),
    ),
    responses(
        (status = 200, description = "Pet found", body = Pet),
        (status = 404, description = "Pet not found"),
    ),
    tag = "pets"
)]
async fn get_pet(Path(id): Path<u64>) -> Json<Pet> {
    // ...
}

3. Generate OpenAPI Document and Serve

use utoipa::OpenApi;
use utoipa_swagger_ui::SwaggerUi;

#[derive(OpenApi)]
#[openapi(
    paths(get_pet, create_pet),
    components(schemas(Pet)),
    tags((name = "pets", description = "Pet management"))
)]
struct ApiDoc;

let app = Router::new()
    .route("/pets/{id}", get(get_pet))
    .merge(SwaggerUi::new("/swagger-ui")
        .url("/api-docs/openapi.json", ApiDoc::openapi()));

Core Macros

Decision Tree: Which Macro Do I Need?

Want to document a Rust type for OpenAPI?
  └─ Struct or enum used in request/response bodies → #[derive(ToSchema)]
  └─ Query/path/header parameters as a struct → #[derive(IntoParams)]

Want to document an API endpoint?
  └─ Always use #[utoipa::path(...)] on the handler function

Want to define response types?
  └─ Responses with status codes built-in → #[derive(IntoResponses)]
  └─ Reusable response (status set at use site) → #[derive(ToResponse)]

Want to assemble the final OpenAPI doc?
  └─ #[derive(OpenApi)] on a unit struct, listing paths + components

Common Patterns

Query Parameters with IntoParams

#[derive(Deserialize, IntoParams)]
#[into_params(parameter_in = Query)]
struct PaginationParams {
    #[param(minimum = 1)]
    page: u64,
    #[param(minimum = 1, maximum = 100, default = 20)]
    per_page: u64,
}

#[utoipa::path(get, path = "/items", params(PaginationParams))]
async fn list_items(Query(params): Query<PaginationParams>) -> Json<Vec<Item>> { ... }

Security Schemes via Modify Trait

struct SecurityAddon;

impl utoipa::Modify for SecurityAddon {
    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
        if let Some(components) = openapi.components.as_mut() {
            components.add_security_scheme(
                "bearer_auth",
                SecurityScheme::Http(
                    HttpBuilder::new()
                        .scheme(HttpAuthScheme::Bearer)
                        .bearer_format("JWT")
                        .build(),
                ),
            );
        }
    }
}

#[derive(OpenApi)]
#[openapi(
    modifiers(&SecurityAddon),
    security(("bearer_auth" = []))
)]
struct ApiDoc;

Enum Variants in OpenAPI

// Simple string enum
#[derive(Serialize, ToSchema)]
enum PetStatus { Available, Pending, Sold }

// Tagged enum (discriminator)
#[derive(Serialize, ToSchema)]
#[serde(tag = "type")]
enum Animal {
    Dog { breed: String },
    Cat { color: String },
}

// Untagged enum (oneOf)
#[derive(Serialize, ToSchema)]
#[serde(untagged)]
enum AnyValue {
    String(String),
    Number(f64),
}

Generic Wrapper Types

#[derive(ToSchema)]
struct Page<T> {
    items: Vec<T>,
    total: u64,
}

#[derive(OpenApi)]
#[openapi(components(schemas(Page<Pet>)))]
struct ApiDoc;

Multipart File Upload

#[derive(ToSchema)]
struct UploadForm {
    name: String,
    file: Vec<u8>,
}

#[utoipa::path(
    post,
    path = "/upload",
    request_body(content = inline(UploadForm), content_type = "multipart/form-data"),
    responses((status = 200, description = "Upload successful"))
)]
async fn upload(form: Multipart) -> impl IntoResponse { ... }

Framework Integration at a Glance

Alternative UIs: Redoc, RapiDoc, Scalar -- see references/integrations.md.

Cargo Features (Quick Reference)

Full feature list: references/cargo-features.md

Serde Compatibility

Utoipa respects serde attributes automatically. When both #[serde(...)] and #[schema(...)] are present, serde wins for shared attributes.

Key serde attributes that affect OpenAPI output:

• rename_all, rename -- field/variant names
• skip, skip_serializing -- excluded from schema
• skip_serializing_if -- makes field non-required
• tag, content, untagged -- enum representation
• flatten -- merges fields via allOf
• default -- makes fields non-required

Reference Files

Troubleshooting

Schema not appearing in OpenAPI output

Register it explicitly in components(schemas(YourType)) or use it in a #[utoipa::path] response/request body (auto-collected).

Recursive types cause panic

Add #[schema(no_recursion)] on the field that creates the cycle.

404 on Swagger UI in debug builds

Add debug-embed feature to utoipa-swagger-ui.

Serde rename not reflected

Serde attributes take precedence. Remove conflicting #[schema(rename)] attributes.

Source: Executioner1939/claude-code-skills — distributed by TomeVault.