Derive Macro utoipa::IntoParams
source · [−]#[derive(IntoParams)]
{
// Attributes available to this derive:
#[param]
#[into_params]
}
Expand description
IntoParams derive macro.
This is #[derive]
implementation for IntoParams
trait.
Typically path parameters need to be defined within #[utoipa::path(...params(...))]
section
for the endpoint. But this trait eliminates the need for that when struct
s are used to define parameters.
Still std::primitive
and String
path parameters or tuple
style path parameters need to be defined
within params(...)
section if description or other than default configuration need to be given.
You can use the Rust’s own #[deprecated]
attribute on field to mark it as
deprecated and it will reflect to the generated OpenAPI spec.
#[deprecated]
attribute supports adding additional details such as a reason and or since version
but this is is not supported in OpenAPI. OpenAPI has only a boolean flag to determine deprecation.
While it is totally okay to declare deprecated with reason
#[deprecated = "There is better way to do this"]
the reason would not render in OpenAPI spec.
IntoParams Container Attributes for #[into_params(...)]
The following attributes are available for use in on the container attribute #[into_params(...)]
for the struct
deriving IntoParams
:
names(...)
Define comma seprated list of names for unnamed fields of struct used as a path parameter.style = ...
Defines how all parameters are serialized byParameterStyle
. Default values are based onparameter_in
attribute.parameter_in = ...
= Defines where the parameters of this field are used with a value fromopenapi::path::ParameterIn
. There is no default value, if this attribute is not supplied, then the value is determined by theparameter_in_provider
inIntoParams::into_params()
.
IntoParams Field Attributes for #[param(...)]
The following attributes are available for use in the #[param(...)]
on struct fields:
style = ...
Defines how the parameter is serialized byParameterStyle
. Default values are based onparameter_in
attribute.explode
Defines whether newparameter=value
pair is created for each parameter withingobject
orarray
.allow_reserved
Defines whether reserved characters:/?#[]@!$&'()*+,;=
is allowed within value.example = ...
Can be literal value, method reference orjson!(...)
. 1 Given example will override any example in underlying parameter type.value_type = ...
Can be used to override default type derived from type of the field used in OpenAPI spec. This is useful in cases where the default type does not correspond to the actual type e.g. when any third-party types are used which are notToSchema
s norprimitive
types. Value can be any Rust type what normally could be used to serialize to JSON or custom type such asObject
.Object
will be rendered as generic OpenAPI object.inline
If set, the schema for this field’s type needs to be aToSchema
, and the schema definition will be inlined.
Note! #[into_params(...)]
is only supported on unnamed struct types to declare names for the arguments.
Use names
to define name for single unnamed argument.
#[derive(IntoParams)]
#[into_params(names("id"))]
struct Id(u64);
Use names
to define names for multiple unnamed arguments.
#[derive(IntoParams)]
#[into_params(names("id", "name"))]
struct IdAndName(u64, String);
Examples
Demonstrate IntoParams
usage with resolving Path
and Query
parameters
for get_pet
endpoint. 2
use actix_web::{get, HttpResponse, Responder};
use actix_web::web::{Path, Query};
use serde::Deserialize;
use serde_json::json;
use utoipa::IntoParams;
#[derive(Deserialize, IntoParams)]
struct PetPathArgs {
/// Id of pet
id: i64,
/// Name of pet
name: String,
}
#[derive(Deserialize, IntoParams)]
struct Filter {
/// Age filter for pets
#[deprecated]
#[param(style = Form, explode, allow_reserved, example = json!([10]))]
age: Option<Vec<i32>>,
}
#[utoipa::path(
params(PetPathArgs, Filter),
responses(
(status = 200, description = "success response")
)
)]
#[get("/pet/{id}/{name}")]
async fn get_pet(pet: Path<PetPathArgs>, query: Query<Filter>) -> impl Responder {
HttpResponse::Ok().json(json!({ "id": pet.id }))
}
Demonstrate IntoParams
usage with the #[into_params(...)]
container attribute to
be used as a path query, and inlining a schema query field:
use serde::Deserialize;
use utoipa::{IntoParams, ToSchema};
#[derive(Deserialize, ToSchema)]
#[serde(rename_all = "snake_case")]
enum PetKind {
Dog,
Cat,
}
#[derive(Deserialize, IntoParams)]
#[into_params(style = Form, parameter_in = Query)]
struct PetQuery {
/// Name of pet
name: Option<String>,
/// Age of pet
age: Option<i32>,
/// Kind of pet
#[param(inline)]
kind: PetKind
}
#[utoipa::path(
get,
path = "/get_pet",
params(PetQuery),
responses(
(status = 200, description = "success response")
)
)]
async fn get_pet(query: PetQuery) {
// ...
}
Override String
with i64
using value_type
attribute.
#[derive(IntoParams)]
#[into_params(parameter_in = Query)]
struct Filter {
#[param(value_type = i64)]
id: String,
}
Override String
with Object
using value_type
attribute. Object
will render as type: object
in OpenAPI spec.
#[derive(IntoParams)]
#[into_params(parameter_in = Query)]
struct Filter {
#[param(value_type = Object)]
id: String,
}
You can use a generic type to override the default type of the field.
#[derive(IntoParams)]
#[into_params(parameter_in = Query)]
struct Filter {
#[param(value_type = Option<String>)]
id: String
}
You can even overide a Vec
with another one.
#[derive(IntoParams)]
#[into_params(parameter_in = Query)]
struct Filter {
#[param(value_type = Vec<i32>)]
id: Vec<String>
}
We can override value with another ToSchema
.
#[derive(ToSchema)]
struct Id {
value: i64,
}
#[derive(IntoParams)]
#[into_params(parameter_in = Query)]
struct Filter {
#[param(value_type = Id)]
id: String
}