Crate axum_autoroute 

Axum Autoroute

The goal of this crate is to integrate utoipa tightly with axum to enforce that for each REST route, the code and the openapi documentation are matching.

Features

• Automatic detection of many axum extractors (Path, Query, Json, TypedMultipart etc.) from the function signature.
  • Detected extractors will be added to the openapi specification.
• Strict route responses.
  • An enum will be automatically generated from the route declared responses and will be enforced as the return type of the function. This ensures that the responses returned by the handler function are matching with the ones declared in the openapi specification.
• AutorouteApiRouter, an axum router keeping track of the openapi documentation and allowing the distinction between public and private (not documented in the openapi specification) routes.
  • Based on utoipa_axum OpenApiRouter.

Example

use axum::extract::{Json, Path, Query};
use axum_autoroute::{AutorouteApiRouter, autoroute, method_routers};

pub fn router() -> AutorouteApiRouter {
    AutorouteApiRouter::new().with_pub_routes(method_routers!(my_route))
}

#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
/// Data to extract from the url path
struct PathParam {
    id: u8,
}

#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
/// Data to extract from the url query
struct QueryParam {
    text1: String,
}

#[derive(Debug, serde::Deserialize, utoipa::ToSchema)]
/// Data to extract from the json request body
struct JsonRequest {
    text2: String,
}

#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
/// Data to send in the response json body
struct JsonResponse {
    id: u8,
    text1: String,
    text2: String,
}

/// This route uses several different axum extractors.
/// It replies either:
/// * An HTTP code 400 (bad request) with an error message if the id is odd.
/// * An HTTP code 200 (ok) with a json structure summarizing all the extracted data if the id is even.
#[autoroute(GET, path="/my/route/{id}",
    responses=[
        (OK, body=JsonResponse, description="The id is even, return the extracted data."),
        (BAD_REQUEST, body=String, serializer=NONE, description="The id is odd, return an error message."),
    ]
)]
async fn my_route(
    Path(path): Path<PathParam>,     // path extraction
    Query(query): Query<QueryParam>, // query extraction
    Json(json): Json<JsonRequest>,   // json body extraction
) -> MyRouteResponses {
    if path.id % 2 != 0 {
        // a response can be returned by using an into_... function corresponding to the http return code
        // (here `IntoBadRequest` which exposes the functions `into_bad_request` and `into_400`)
        format!("The provided id ({}) is odd.", path.id).into_bad_request()
    } else {
        let resp = JsonResponse {
            id: path.id,
            text1: query.text1,
            text2: json.text2,
        };        
        resp.into_200()
    }
}

See the axum-autoroute-example crate for more samples.

Crate features

• debugging: Enables the [autoroute_debug] macro.
• tracing: Enables automatic tracing of input/output parameters of the handlers.
  • The parameters will be displayed using their Debug implementation.
• default_serializer_json (default): If enabled, the default serializer for autoroute responses will be Json.
• unstable_extractor_attr: Enables some unstable extractor attribute fields.

Modules

response

Utilities to generate Response with an associated OpenApi documentation.

status_trait

Collection of traits to return responses from an autoroute function. These traits will be automatically implemented by the autoroute macro based on responses declaration. A trait exists for each HTTP status code.

Macros

method_router

Returns an UtoipaMethodRouter from the name of an handler.

method_routers

Returns an array of UtoipaMethodRouter from a list of handlers name.

route_info

Returns a RouteInfo from the name of an handler.

routes_info

Returns an array of RouteInfo from a list of handlers name.

Structs

AutorouteApiRouter

A wrapper of utoipa_axum::router::OpenApiRouter allowing to separate public and private (not appearing in the openapi specification) routes. If unspecified, the state of the router will be the unit type.

RouteInfo

A structure holding information about a route handler (namely its method and path) A new instance of this struct will be implemented by each autoroute handler.

Attribute Macros

autoroute

Macro to put on top of an axum handler function. It will be used to define several info about the handler (method, path, allowed responses) and will also extract others from the function signature.