#[derive(OpenApi)]
{
// Attributes available to this derive:
#[openapi]
}
Expand description
OpenApi derive macro.
This is #[derive]
implementation for OpenApi
trait. The macro accepts one openapi
argument.
Accepted argument attributes:
paths(...)
List of method references having attribute#[utoipa::path]
macro.components(schemas(...), responses(...))
Takes availablecomponent
configurations. Currently onlyschema
andresponse
components are supported.schemas(...)
List ofToSchema
s in OpenAPI schema.responses(...)
List of types that implementToResponse
.
modifiers(...)
List of items implementingModify
trait for runtime OpenApi modification. See the trait documentation for more details.security(...)
List ofSecurityRequirement
s global to all operations. See more details in#[utoipa::path(...)]
attribute macro security options.tags(...)
List ofTag
which must match the tag path operation. By default the tag is derived from path given to handlers list or if undefined thencrate
is used by default. Alternatively the tag name can be given to path operation via#[utoipa::path(...)]
macro. Tag can be used to define extra information for the api to produce richer documentation.external_docs(...)
Can be used to reference external resource to the OpenAPI doc for extended documentation. External docs can be inOpenApi
or inTag
level.
OpenApi derive macro will also derive Info
for OpenApi specification using Cargo
environment variables.
- env
CARGO_PKG_NAME
map to infotitle
- env
CARGO_PKG_VERSION
map to infoversion
- env
CARGO_PKG_DESCRIPTION
map infodescription
- env
CARGO_PKG_AUTHORS
map to contactname
andemail
only first author will be used - env
CARGO_PKG_LICENSE
map to infolicense
Examples
Define OpenApi schema with some paths and components.
#[derive(ToSchema)]
struct Pet {
name: String,
age: i32,
}
#[derive(ToSchema)]
enum Status {
Active, InActive, Locked,
}
#[utoipa::path(get, path = "/pet")]
fn get_pet() -> Pet {
Pet {
name: "bob".to_string(),
age: 8,
}
}
#[utoipa::path(get, path = "/status")]
fn get_status() -> Status {
Status::Active
}
#[derive(OpenApi)]
#[openapi(
paths(get_pet, get_status),
components(schemas(Pet, Status)),
security(
(),
("my_auth" = ["read:items", "edit:items"]),
("token_jwt" = [])
),
tags(
(name = "pets::api", description = "All about pets",
external_docs(url = "http://more.about.pets.api", description = "Find out more"))
),
external_docs(url = "http://more.about.our.apis", description = "More about our APIs")
)]
struct ApiDoc;