Expand description
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
Existing examples for following frameworks:
- actix-web
- axum
- warp
- tide
- rocket
Even if there is no example for your favorite 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 integration with being able to
parse
path
andpath 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 theparameter_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
andDuration
types. By default these types are parsed tostring
types with additionalformat
information.format: date-time
forDateTime
andformat: date
forDate
according RFC3339 asISO-8601
. To override defaultstring
representation users have to usevalue_type
attribute to override the type. See docs for more details. - time Add support for time
OffsetDateTime
,PrimitiveDateTime
,Date
, andDuration
types. By default these types are parsed asstring
.OffsetDateTime
andPrimitiveDateTime
will usedate-time
format.Date
will usedate
format andDuration
will not have any format. To override defaultstring
representation users have to usevalue_type
attribute to override the type. See docs for more details. - decimal Add support for rust_decimal
Decimal
type. By default it is interpreted asString
. If you wish to change the format you need to override the type. See thevalue_type
inToSchema
derive docs. - uuid Add support for uuid.
Uuid
type will be presented asString
with formatuuid
in OpenAPI spec. - smallvec Add support for smallvec.
SmallVec
will be treated asVec
. - openapi_extensions Adds convenience functions for documenting common scenarios, such as JSON request bodies and responses.
See the
request_body
andresponse
docs for examples.
Utoipa implicitly has partial support for serde
attributes. See ToSchema
derive for more details.
Install
Add minimal dependency declaration to Cargo.toml.
[dependencies]
utoipa = "2"
To enable more features such as use actix framework extras you could define the dependency as follows.
[dependencies]
utoipa = { version = "2", 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 ToSchema
derive macro to it so it can be registered
as a component in openapi schema.
use utoipa::ToSchema;
#[derive(ToSchema)]
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 successfully", 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(paths(pet_api::get_pet_by_id), components(schemas(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 comprehensive examples.
- Modify generated OpenAPI at runtime check
Modify
trait for more details. - More about OpenAPI security in security documentation.
Modules
Rust implementation of Openapi Spec V3.
Traits
Trait used to convert implementing type to OpenAPI parameters.
This trait is implemented to document a type (like an enum) which can represent multiple responses, to be used in an operation.
Trait that allows OpenApi modification at runtime.
Trait for implementing OpenAPI specification in Rust.
Trait for implementing OpenAPI PathItem object with path.
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.
Trait for implementing OpenAPI Schema object.
Attribute Macros
Path attribute macro.