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 auto generated 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 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.
Existing examples for following frameworks:
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.
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 :beer:.
example value. This is enabled by default.path and path and query parameters from actix web path attribute macros. See
docs or examples for more details.path, path and query parameters from rocket path attribute macros. See docs
or examples for more details.IntoParams without defining the parameter_in attribute. See
docs or examples for more details.DateTime, Date 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 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.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 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 type will be presented as String with
format uuid in OpenAPI spec.SmallVec will be treated as Vec.request_body docs for an example.Utoipa implicitly has partial support for serde attributes. See docs for more details.
Add minimal dependency declaration to Cargo.toml.
toml
[dependencies]
utoipa = "2"
To enable more features such as use actix framework extras you could define the
dependency as follows.
toml
[dependencies]
utoipa = { version = "2", features = ["actix_extras"] }
Note! To use utoipa together with Swagger UI you can use the utoipa-swagger-ui crate.
Create a struct or it could be an enum also. Add ToSchema derive macro to it so it can be registered
as an an OpenAPI schema.
```rust
use utoipa::ToSchema;
struct Pet {
id: u64,
name: String,
age: Option
Create a handler that would handle your business logic and add path proc attribute macro over it.
rust
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 Schema and the endpoint above to the OpenApi schema with following OpenApi derive proc macro.
```rust
use utoipa::OpenApi;
struct ApiDoc;
println!("{}", ApiDoc::openapi().toprettyjson().unwrap()); ```
This would produce api doc something similar to:
json
{
"openapi": "3.0.3",
"info": {
"title": "application name from Cargo.toml",
"description": "description from Cargo.toml",
"contact": {
"name": "author name from Cargo.toml",
"email":"author email from Cargo.toml"
},
"license": {
"name": "license from Cargo.toml"
},
"version": "version from Cargo.toml"
},
"paths": {
"/pets/{id}": {
"get": {
"tags": [
"pet_api"
],
"summary": "Get pet by id",
"description": "Get pet by id\n\nGet pet from database by pet id\n",
"operationId": "get_pet_by_id",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Pet database id to get Pet for",
"required": true,
"deprecated": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Pet found succesfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"404": {
"description": "Pet was not found"
}
},
"deprecated": false
}
}
},
"components": {
"schemas": {
"Pet": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
}
}
Licensed under either of Apache 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, shall be dual licensed, without any additional terms or conditions.