utoipa

Trait Path

Source
pub trait Path {
    // Required methods
    fn methods() -> Vec<HttpMethod>;
    fn path() -> String;
    fn operation() -> Operation;
}
Expand description

Trait for implementing OpenAPI PathItem object with path.

This trait is implemented via #[utoipa::path(...)] attribute macro and there is no need to implement this trait manually.

§Examples

Use #[utoipa::path(..)] to implement Path trait

/// Get pet by id
///
/// Get pet from database by pet database 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,
        name: "lightning".to_string(),
    }
}

Example of what would manual implementation roughly look like of above #[utoipa::path(...)] macro.

utoipa::openapi::PathsBuilder::new().path(
        "/pets/{id}",
        utoipa::openapi::PathItem::new(
            utoipa::openapi::HttpMethod::Get,
            utoipa::openapi::path::OperationBuilder::new()
                .responses(
                    utoipa::openapi::ResponsesBuilder::new()
                        .response(
                            "200",
                            utoipa::openapi::ResponseBuilder::new()
                                .description("Pet found successfully")
                                .content("application/json",
                                    utoipa::openapi::Content::new(
                                        Some(utoipa::openapi::Ref::from_schema_name("Pet")),
                                    ),
                            ),
                        )
                        .response("404", utoipa::openapi::Response::new("Pet was not found")),
                )
                .operation_id(Some("get_pet_by_id"))
                .deprecated(Some(utoipa::openapi::Deprecated::False))
                .summary(Some("Get pet by id"))
                .description(Some("Get pet by id\n\nGet pet from database by pet database id\n"))
                .parameter(
                    utoipa::openapi::path::ParameterBuilder::new()
                        .name("id")
                        .parameter_in(utoipa::openapi::path::ParameterIn::Path)
                        .required(utoipa::openapi::Required::True)
                        .deprecated(Some(utoipa::openapi::Deprecated::False))
                        .description(Some("Pet database id to get Pet for"))
                        .schema(
                            Some(utoipa::openapi::ObjectBuilder::new()
                                .schema_type(utoipa::openapi::schema::Type::Integer)
                                .format(Some(utoipa::openapi::SchemaFormat::KnownFormat(utoipa::openapi::KnownFormat::Int64)))),
                        ),
                )
                .tag("pet_api"),
        ),
    );

Required Methods§

Source

fn methods() -> Vec<HttpMethod>

List of HTTP methods this path operation is served at.

Source

fn path() -> String

The path this operation is served at.

Source

fn operation() -> Operation

openapi::path::Operation describing http operation details such as request bodies, parameters and responses.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§

Source§

impl<T: PathConfig> Path for T