Derive Macro utoipa::IntoParams

#[derive(IntoParams)]
{
    // Attributes available to this derive:
    #[param]
}

IntoParams derive macro for actix-web only.

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 structs 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 addtional 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 Attributes for #[param(...)]

• style = ... Defines how parameters are serialized by ParameterStyle. Default values are based on in attribute.
• explode Defines whether new parameter=value is created for each parameter withing object or array.
• allow_reserved Defines whether reserved charachers :/?#[]@!$&'()*+,;= is allowed within value.
• example = ... Can be literal value, method reference or json!(...). ¹ Given example will override any example in underlying parameter type.

Examples

Demonstrate IntoParams usage with resolving path and query parameters for get_pet endpoint. ²

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(
    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 }))
}

---

1. json feature need to be enabled for json!(...) type to work. ↩

2. Feature actix_extras need to be enabled ↩