diff --git a/src/lib.rs b/src/lib.rs index 4d72df36..f8702154 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,7 +9,7 @@ //! - [Precedence](#precedence) //! - [Matching multiple methods](#matching-multiple-methods) //! - [Routing to any `Service`](#routing-to-any-service) -//! - [Nesting Routes](#nesting-routes) +//! - [Nesting routes](#nesting-routes) //! - [Extractors](#extractors) //! - [Building responses](#building-responses) //! - [Applying middleware](#applying-middleware) @@ -255,7 +255,7 @@ //! Routing to arbitrary services in this way has complications for backpressure //! ([`Service::poll_ready`]). See the [`service`] module for more details. //! -//! ## Nesting Routes +//! ## Nesting routes //! //! Routes can be nested by calling [`Router::nest`](routing::Router::nest): //! diff --git a/src/routing/mod.rs b/src/routing/mod.rs index 3de4d341..9770871e 100644 --- a/src/routing/mod.rs +++ b/src/routing/mod.rs @@ -143,8 +143,8 @@ impl Router { /// use http::Uri; /// /// async fn users_get(uri: Uri) { - /// // `users_get` will still see the whole URI. - /// assert_eq!(uri.path(), "/api/users"); + /// // `uri` will be `/users` since `nest` strips the matching prefix. + /// // use `OriginalUri` to always get the full URI. /// } /// /// async fn users_post() {} @@ -153,12 +153,19 @@ impl Router { /// /// let users_api = Router::new().route("/users", get(users_get).post(users_post)); /// - /// let app = Router::new().nest("/api", users_api).route("/careers", get(careers)); + /// let app = Router::new() + /// .nest("/api", users_api) + /// .route("/careers", get(careers)); /// # async { /// # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap(); /// # }; /// ``` /// + /// Note that nested routes will not see the orignal request URI but instead + /// have the matched prefix stripped. This is necessary for services like static + /// file serving to work. Use [`OriginalUri`] if you need the original request + /// URI. + /// /// Take care when using `nest` together with dynamic routes as nesting also /// captures from the outer routes: /// @@ -207,6 +214,8 @@ impl Router { /// If necessary you can use [`Router::boxed`] to box a group of routes /// making the type easier to name. This is sometimes useful when working with /// `nest`. + /// + /// [`OriginalUri`]: crate::extract::OriginalUri pub fn nest(self, description: &str, svc: T) -> Router> { self.map(|fallback| Nested { pattern: PathPattern::new(description),