Crate utoipa

Expand description

Want to have your API documented with OpenAPI? But you dont 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 appoach 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 autogeneration 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

Existing examples for following frameworks:

actix-web
warp
tide
rocket

Even if there is no example for your favourite framework utoipa can be used with any web framework which supports decorating functions with macros similarly to warp and tide examples.

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.

Features

default Default enabled features are json.
json Enables serde_json serialization of OpenAPI objects which also allows usage of JSON within OpenAPI values e.g. within example value. This is enabled by default.
yaml Enables serde_yaml serialization of OpenAPI objects.
actix_extras Enhances actix-web intgration with being able to parse path and 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
debug Add extra traits such as debug traits to openapi definitions and elsewhere.
chrono Add support for chrono DateTime, Date and Duration types. By default these types are parsed to string types without additional format. If you want to have formats added to the types use chrono_with_format feature. This is useful because OpenAPI 3.1 spec does not have date-time formats.
chrono_with_format Add support to chrono types described above with additional format information type. date-time for DateTime and date for Date according RFC3339 as ISO-8601.
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 component derive docs.
uuid Add support for uuid. Uuid type will be presented as String with format uuid in OpenAPI spec.

Utoipa implicitly has partial support for serde attributes. See component derive for more details.

Install

Add minimal dependency declaration to Cargo.toml.

[dependencies]
utoipa = "1.0.0"

To enable more features such as use actix framework extras you could define the dependency as follows.

[dependencies]
utoipa = { version = "1.0.0", features = ["actix_extras"] }

Note! To use utoipa together with Swagger UI you can use the utoipa-swagger-ui crate.

Examples

Create a struct or it could be an enum also. Add Component derive macro to it so it can be registered as a component in openapi schema.

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

Create an handler that would handle your business logic and add path proc attribute macro over it.

mod pet_api {
    /// Get pet by id
    ///
    /// Get pet from database by pet id  
    #[utoipa::path(
        get,
        path = "/pets/{id}",
        responses(
            (status = 200, description = "Pet found succesfully", body = Pet),
            (status = 404, 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) -> Pet {
        Pet {
            id: pet_id,
            age: None,
            name: "lightning".to_string(),
        }
    }
}

Tie the component and the above api to the openapi schema with following OpenApi derive proc macro.

#[derive(OpenApi)]
#[openapi(handlers(pet_api::get_pet_by_id), components(Pet))]
struct ApiDoc;

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

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 comprehensinve examples.
Modify generated OpenAPI at runtime check Modify trait for more details.
More about OpenAPI security in security documentation.