utoipa

utoipa is a Rust crate designed to provide auto-generated OpenAPI documentation for REST APIs. It follows a code-first approach, using procedural macros to annotate your code, which minimizes the need for manual YAML or JSON documentation maintenance. It is framework-agnostic, meaning it can be used standalone or integrated with various web frameworks.

Key features include:

• Support for OpenAPI 3.1.
• Automatic schema collection from request bodies (via handler arguments or request_body attribute) and response bodies (via body or content attributes).
• Support for generic types (with limitations on tuples, arrays, and slices).
• Support for various OpenAPI visualization tools.
• Pluggable setup for easy integration with web frameworks.

Use utoipa-actix-web to recursively collect paths and schemas from Actix Web App, Scope, and ServiceConfig. This reduces duplication by eliminating the need to manually declare paths and schemas in the #[openapi(...)] attribute of your OpenApi derive macro.

Note: Automatic collection currently only works with service(...) calls. Manual routes defined via route(...) or Route::new().to(...) are not supported.

use actix_web::{get, App};
use utoipa_actix_web::{scope, AppExt};

#[derive(utoipa::ToSchema)]
struct User {
    id: i32,
}

#[utoipa::path(responses((status = OK, body = User)))]
#[get("/user")]
async fn get_user() -> Json<User> {
    Json(User { id: 1 })
}

let (_, mut api) = App::new()
    .into_utoipa_app()
    .service(scope::scope("/api/v1").service(get_user))
    .split_for_parts();

To use utoipa-config for global configuration, add it to your [build-dependencies] section in Cargo.toml.

[build-dependencies]
utoipa-config = "0.1"

Add utoipa-actix-web to your Cargo.toml dependencies to enable automatic collection of OpenAPI paths and schemas from Actix Web components.

[dependencies]
utoipa-actix-web = "0.1"

Once the todo-rocket application is running, you can access different OpenAPI documentation interfaces at the following endpoints:

• Swagger UI: http://localhost:8000/swagger-ui/
• Redoc: http://localhost:8000/redoc
• RapiDoc: http://localhost:8000/redoc (Note: The README indicates RapiDoc is also available at this path)
• Scalar: http://localhost:8000/scalar

The demo application provides multiple API definitions. You can switch between them using the "Select a definition" drop-down menu in the Swagger UI. Alternatively, you can load a specific definition directly via URL parameters using urls.primaryName:

• API 1: http://localhost:8080/swagger-ui/?urls.primaryName=%2Fapi-doc1.json
• API 2: http://localhost:8080/swagger-ui/?urls.primaryName=%2Fapi-doc2.json

Once the todo-actix application is running, you can access the generated OpenAPI documentation through several different UI interfaces at the following endpoints:

• Swagger UI: http://localhost:8080/swagger-ui/
• Redoc: http://localhost:8080/redoc
• RapiDoc: http://localhost:8080/rapidoc
• Scalar: http://localhost:8080/scalar

The utoipa-swagger-ui-vendored crate contains the Swagger UI (version 5.32.6) assets re-packaged as a Rust crate. It is designed to be used as a build dependency for the utoipa-swagger-ui crate.

By enabling the vendored feature on the utoipa-swagger-ui crate, you can serve Swagger UI in sandboxed environments where network access is restricted or where external assets cannot be provided.

The todo-axum example is a demo axum application using in-memory storage to manage Todo items. It demonstrates how to integrate utoipa with various OpenAPI UI tools like utoipa-swagger-ui, utoipa-redoc, utoipa-rapidoc, and scalar.

To run the application, use the following command:

cargo run

The todo-actix example is a demo actix-web application using in-memory storage. It demonstrates how to use utoipa alongside various OpenAPI UI tools like utoipa-swagger-ui, utoipa-redoc, utoipa-rapidoc, and scalar.

To run the application, use:

cargo run

To enable debug logging, prepend the command with RUST_LOG=debug:

RUST_LOG=debug cargo run