Trait Path

Help

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"),
        ),
    );