Crate utoipa

Want to have your API documented with OpenAPI? But you don’t want to see the trouble with manual yaml or json tweaking? Would like it to be so easy that it would almost be like utopic? Don’t worry utoipa is just there to fill this gap. It aims to do if not all then the most of heavy lifting for you enabling you to focus writing the actual API logic instead of documentation. It aims to be minimal, simple and fast. It uses simple proc macros which you can use to annotate your code to have items documented.

Utoipa crate provides autogenerated OpenAPI documentation for Rust REST APIs. It treats code first approach as a first class citizen and simplifies API documentation by providing simple macros for generating the documentation from your code.

It also contains Rust types of OpenAPI spec allowing you to write the OpenAPI spec only using Rust if auto-generation is not your flavor or does not fit your purpose.

Long term goal of the library is to be the place to go when OpenAPI documentation is needed in Rust codebase.

Utoipa is framework agnostic and could be used together with any web framework or even without one. While being portable and standalone one of it’s key aspects is simple integration with web frameworks.

Currently utoipa provides simple integration with actix-web framework but is not limited to the actix-web framework. All functionalities are not restricted to any specific framework.

Choose your flavor and document your API with ice cold IPA

Flavor	Support
actix-web	Parse path, path parameters and query parameters, recognize request body and response body, utoipa-actix-web bindings. See more at docs
axum	Parse path and query parameters, recognize request body and response body, utoipa-axum bindings. See more at docs
rocket	Parse path, path parameters and query parameters, recognize request body and response body. See more at docs
Others*	Plain utoipa without extra flavor. This gives you all the basic benefits listed below in Features section but with little less automation.

Others* = For example warp but could be anything.

Refer to the existing examples to find out more.

Features

• OpenAPI 3.1
• Pluggable, easy setup and integration with frameworks.
• No bloat, enable what you need.
• Support for generic types
  • Note!
    Tuples, arrays and slices cannot be used as generic arguments on types. Types implementing ToSchema manually should not have generic arguments, as they are not composeable and will result compile error.
• Automatic schema collection from usages recursively.
  • Request body from either handler function arguments (if supported by framework) or from request_body attribute.
  • Response body from response body attribute or response content attribute.
• Various OpenAPI visualization tools supported out of the box.
• Rust type aliases via utoipa-config.

What’s up with the word play?

The name comes from words utopic and api where uto is the first three letters of utopic and the ipa is api reversed. Aaand… ipa is also awesome type of beer.

Crate Features

• macros Enable utoipa-gen macros. This is enabled by default.
• yaml Enables serde_yaml serialization of OpenAPI objects.
• actix_extras Enhances actix-web integration with being able to parse path, path and query parameters from actix web path attribute macros. See actix extras support or examples for more details.
• rocket_extras Enhances rocket framework integration with being able to parse path, path and query parameters from rocket path attribute macros. See rocket extras support or examples for more details
• axum_extras Enhances axum framework integration allowing users to use IntoParams without defining the parameter_in attribute. See axum extras support or examples for more details.
• debug Add extra traits such as debug traits to openapi definitions and elsewhere.
• chrono Add support for chrono DateTime, Date, NaiveDate, NaiveTime and Duration types. By default these types are parsed to string types with additional format information. format: date-time for DateTime and format: date for Date and NaiveDate according RFC3339 as ISO-8601. To override default string representation users have to use value_type attribute to override the type. See docs for more details.
• time Add support for time OffsetDateTime, PrimitiveDateTime, Date, and Duration types. By default these types are parsed as string. OffsetDateTime and PrimitiveDateTime will use date-time format. Date will use date format and Duration will not have any format. To override default string representation users have to use value_type attribute to override the type. See docs for more details.
• decimal Add support for rust_decimal Decimal type. By default it is interpreted as String. If you wish to change the format you need to override the type. See the value_type in ToSchema derive docs.
• decimal_float Add support for rust_decimal Decimal type. By default it is interpreted as Number. This feature is mutually exclusive with decimal and allow to change the default type used in your documentation for Decimal much like serde_with_float feature exposed by rust_decimal.
• uuid Add support for uuid. Uuid type will be presented as String with format uuid in OpenAPI spec.
• ulid Add support for ulid. Ulid type will be presented as String with format ulid in OpenAPI spec.
• url Add support for url. Url type will be presented as String with format uri in OpenAPI spec.
• smallvec Add support for smallvec. SmallVec will be treated as Vec.
• openapi_extensions Adds convenience functions for documenting common scenarios, such as JSON request bodies and responses. See the request_body and response docs for examples.
• repr Add support for repr_serde’s repr(u*) and repr(i*) attributes to unit type enums for C-like enum representation. See docs for more details.
• preserve_order Preserve order of properties when serializing the schema for a component. When enabled, the properties are listed in order of fields in the corresponding struct definition. When disabled, the properties are listed in alphabetical order.
• preserve_path_order Preserve order of OpenAPI Paths according to order they have been introduced to the #[openapi(paths(...))] macro attribute. If disabled the paths will be ordered in alphabetical order. However the operations order under the path will be always constant according to specification
• indexmap Add support for indexmap. When enabled IndexMap will be rendered as a map similar to BTreeMap and HashMap.
• non_strict_integers Add support for non-standard integer formats int8, int16, uint8, uint16, uint32, and uint64.
• rc_schema Add ToSchema support for Arc<T> and Rc<T> types. Note! serde rc feature flag must be enabled separately to allow serialization and deserialization of Arc<T> and Rc<T> types. See more about serde feature flags.
• config Enables utoipa-config for the project which allows defining global configuration options for utoipa.

Default Library Support

• Implicit partial support for serde attributes. See ToSchema derive for more details.
• Support for http StatusCode in responses.

Install

Add dependency declaration to Cargo.toml.

[dependencies]
utoipa = "5"

Examples

Create type with ToSchema and use it in #[utoipa::path(...)] that is registered to the OpenApi.

use utoipa::{OpenApi, ToSchema};

#[derive(ToSchema)]
struct Pet {
   id: u64,
   name: String,
   age: Option<i32>,
}

/// Get pet by id
///
/// Get pet from database by pet id
#[utoipa::path(
    get,
    path = "/pets/{id}",
    responses(
        (status = 200, description = "Pet found successfully", body = Pet),
        (status = NOT_FOUND, description = "Pet was not found")
    ),
    params(
        ("id" = u64, Path, description = "Pet database id to get Pet for"),
    )
)]
async fn get_pet_by_id(pet_id: u64) -> Result<Pet, NotFound> {
    Ok(Pet {
        id: pet_id,
        age: None,
        name: "lightning".to_string(),
    })
}

#[derive(OpenApi)]
#[openapi(paths(get_pet_by_id))]
struct ApiDoc;

println!("{}", ApiDoc::openapi().to_pretty_json().unwrap());

Modify OpenAPI at runtime

You can modify generated OpenAPI at runtime either via generated types directly or using Modify trait.

Modify generated OpenAPI via types directly.

#[derive(OpenApi)]
#[openapi(
    info(description = "My Api description"),
)]
struct ApiDoc;

let mut doc = ApiDoc::openapi();
doc.info.title = String::from("My Api");

You can even convert the generated OpenApi to openapi::OpenApiBuilder.

#[derive(OpenApi)]
#[openapi(
    info(description = "My Api description"),
)]
struct ApiDoc;

let builder: OpenApiBuilder = ApiDoc::openapi().into();

See Modify trait for examples on how to modify generated OpenAPI via it.

Go beyond the surface

• See how to serve OpenAPI doc via Swagger UI check utoipa-swagger-ui crate for more details.
• Browse to examples for more comprehensive examples.
• Check IntoResponses and ToResponse for examples on deriving responses.
• More about OpenAPI security in security documentation.
• Dump generated API doc to file at build time. See issue 214 comment.

Modules

• openapi
  Rust implementation of Openapi Spec V3.1.

Macros

• schemamacros
  Create OpenAPI Schema from arbitrary type.

Enums

• Number
  Flexible number wrapper used by validation schema attributes to seamlessly support different number syntaxes.

Traits

• IntoParams
  Trait used to convert implementing type to OpenAPI parameters.
• IntoResponses
  This trait is implemented to document a type (like an enum) which can represent multiple responses, to be used in operation.
• Modify
  Trait that allows OpenApi modification at runtime.
• OpenApi
  Trait for implementing OpenAPI specification in Rust.
• PartialSchema
  Trait used to implement only Schema part of the OpenAPI doc.
• Path
  Trait for implementing OpenAPI PathItem object with path.
• ToResponse
  This trait is implemented to document a type which represents a single response which can be referenced or reused as a component in multiple operations.
• ToSchema
  Trait for implementing OpenAPI Schema object.

Type Aliases

• TupleUnit
  Represents nullable type. This can be used anywhere where “nothing” needs to be evaluated. This will serialize to null in JSON and openapi::schema::empty is used to create the openapi::schema::Schema for the type.

Attribute Macros

• pathmacros
  Path attribute macro implements OpenAPI path for the decorated function.

Derive Macros

• IntoParamsmacros
  Generate path parameters from struct’s fields.
• IntoResponsesmacros
  Generate responses with status codes what can be attached to the utoipa::path.
• OpenApimacros
  Generate OpenApi base object with defaults from project settings.
• ToResponsemacros
  Generate reusable OpenAPI response that can be used in utoipa::path or in OpenApi.
• ToSchemamacros
  Generate reusable OpenAPI schema to be used together with OpenApi.