docs: Add doc comment explaining how NormalizePathLayer works (#393)

src/service/http/initializer/normalize_path.rs

@@ -47,6 +47,17 @@ where
             .priority
     }
 
+    /// Add the [`NormalizePathLayer`] to handle a trailing `/` at the end of URIs.
+    ///
+    /// Normally, adding a layer via the axum [`Router::layer`] method causes the layer to run
+    /// after routing has already completed. This means the [`NormalizePathLayer`] would not
+    /// normalize the uri for the purposes of routing, which defeats the point of the layer.
+    /// The workaround is to wrap the entire router with [`NormalizePathLayer`], which is why this
+    /// middleware is applied in an [`Initializer`] instead of as a normal
+    /// [`crate::service::http::middleware::Middleware`] -- this way, the [`NormalizePathLayer`]
+    /// is applied after all the routes and normal middleware have been applied.
+    ///
+    /// See: <https://docs.rs/axum/latest/axum/middleware/index.html#rewriting-request-uri-in-middleware>
     fn before_serve(&self, router: Router, _state: &S) -> RoadsterResult<Router> {
         let router = NormalizePathLayer::trim_trailing_slash().layer(router);
         let router = Router::new().nest_service("/", router);