From 57e440ed2ee145471bd45d4910783eff07efaf30 Mon Sep 17 00:00:00 2001 From: Eduardo Canellas Date: Mon, 16 Aug 2021 04:17:26 -0300 Subject: [PATCH] move relevant docs sections to be under "Routing" (#175) --- src/lib.rs | 132 ++++++++++++++++++++++++++--------------------------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 15add66c..7faeb543 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,6 +8,8 @@ //! - [Routing](#routing) //! - [Precedence](#precedence) //! - [Matching multiple methods](#matching-multiple-methods) +//! - [Routing to any `Service`](#routing-to-any-service) +//! - [Nesting Routes](#nesting-routes) //! - [Extractors](#extractors) //! - [Building responses](#building-responses) //! - [Applying middleware](#applying-middleware) @@ -15,8 +17,6 @@ //! - [To groups of routes](#to-groups-of-routes) //! - [Error handling](#error-handling) //! - [Sharing state with handlers](#sharing-state-with-handlers) -//! - [Routing to any `Service`](#routing-to-any-service) -//! - [Nesting applications](#nesting-applications) //! - [Required dependencies](#required-dependencies) //! - [Examples](#examples) //! - [Feature flags](#feature-flags) @@ -211,6 +211,70 @@ //! # }; //! ``` //! +//! ## Routing to any [`Service`] +//! +//! axum also supports routing to general [`Service`]s: +//! +//! ```rust,no_run +//! use axum::{service, prelude::*}; +//! use tower_http::services::ServeFile; +//! use http::Response; +//! use std::convert::Infallible; +//! use tower::service_fn; +//! +//! let app = route( +//! // Any request to `/` goes to a service +//! "/", +//! // Services who's response body is not `axum::body::BoxBody` +//! // can be wrapped in `axum::service::any` (or one of the other routing filters) +//! // to have the response body mapped +//! service::any(service_fn(|_: Request| async { +//! let res = Response::new(Body::from("Hi from `GET /`")); +//! Ok(res) +//! })) +//! ).route( +//! "/foo", +//! // This service's response body is `axum::body::BoxBody` so +//! // it can be routed to directly. +//! service_fn(|req: Request| async move { +//! let body = Body::from(format!("Hi from `{} /foo`", req.method())); +//! let body = axum::body::box_body(body); +//! let res = Response::new(body); +//! Ok(res) +//! }) +//! ).route( +//! // GET `/static/Cargo.toml` goes to a service from tower-http +//! "/static/Cargo.toml", +//! service::get(ServeFile::new("Cargo.toml")) +//! ); +//! # async { +//! # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap(); +//! # }; +//! ``` +//! +//! Routing to arbitrary services in this way has complications for backpressure +//! ([`Service::poll_ready`]). See the [`service`] module for more details. +//! +//! ## Nesting Routes +//! +//! Routes can be nested by calling [`nest`](routing::nest): +//! +//! ```rust,no_run +//! use axum::{prelude::*, routing::BoxRoute, body::{Body, BoxBody}}; +//! use tower_http::services::ServeFile; +//! use http::Response; +//! +//! fn api_routes() -> BoxRoute { +//! route("/users", get(|_: Request| async { /* ... */ })).boxed() +//! } +//! +//! let app = route("/", get(|_: Request| async { /* ... */ })) +//! .nest("/api", api_routes()); +//! # async { +//! # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap(); +//! # }; +//! ``` +//! //! # Extractors //! //! An extractor is a type that implements [`FromRequest`]. Extractors is how @@ -554,70 +618,6 @@ //! # }; //! ``` //! -//! # Routing to any [`Service`] -//! -//! axum also supports routing to general [`Service`]s: -//! -//! ```rust,no_run -//! use axum::{service, prelude::*}; -//! use tower_http::services::ServeFile; -//! use http::Response; -//! use std::convert::Infallible; -//! use tower::service_fn; -//! -//! let app = route( -//! // Any request to `/` goes to a service -//! "/", -//! // Services who's response body is not `axum::body::BoxBody` -//! // can be wrapped in `axum::service::any` (or one of the other routing filters) -//! // to have the response body mapped -//! service::any(service_fn(|_: Request| async { -//! let res = Response::new(Body::from("Hi from `GET /`")); -//! Ok(res) -//! })) -//! ).route( -//! "/foo", -//! // This service's response body is `axum::body::BoxBody` so -//! // it can be routed to directly. -//! service_fn(|req: Request| async move { -//! let body = Body::from(format!("Hi from `{} /foo`", req.method())); -//! let body = axum::body::box_body(body); -//! let res = Response::new(body); -//! Ok(res) -//! }) -//! ).route( -//! // GET `/static/Cargo.toml` goes to a service from tower-http -//! "/static/Cargo.toml", -//! service::get(ServeFile::new("Cargo.toml")) -//! ); -//! # async { -//! # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap(); -//! # }; -//! ``` -//! -//! Routing to arbitrary services in this way has complications for backpressure -//! ([`Service::poll_ready`]). See the [`service`] module for more details. -//! -//! # Nesting applications -//! -//! Applications can be nested by calling [`nest`](routing::nest): -//! -//! ```rust,no_run -//! use axum::{prelude::*, routing::BoxRoute, body::{Body, BoxBody}}; -//! use tower_http::services::ServeFile; -//! use http::Response; -//! -//! fn api_routes() -> BoxRoute { -//! route("/users", get(|_: Request| async { /* ... */ })).boxed() -//! } -//! -//! let app = route("/", get(|_: Request| async { /* ... */ })) -//! .nest("/api", api_routes()); -//! # async { -//! # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap(); -//! # }; -//! ``` -//! //! # Required dependencies //! //! To use axum there are a few dependencies you have pull in as well: