Rework docs (#437)

This reworks axum's docs in an attempt to make things easier to find. Previously I wasn't a fan of those docs for the same topic were spread across the root module docs and more specific places like types and methods.

This changes it such that the root module docs only gives a high level introduction to a topic, perhaps with a small example, and then link to other places where all the details are. This means `Router` is now the single place to learn about routing, and etc for the topics like handlers and error handling.

examples/hello-world/src/main.rs

@@ -4,23 +4,58 @@
 //! cargo run -p example-hello-world
 //! ```
 
-use axum::{response::Html, routing::get, Router};
-use std::net::SocketAddr;
-
 #[tokio::main]
 async fn main() {
-    // build our application with a route
-    let app = Router::new().route("/", get(handler));
+    use axum::async_trait;
+    use axum::http::StatusCode;
+    use axum::{
+        extract::{extractor_middleware, FromRequest, RequestParts},
+        routing::{get, post},
+        Router,
+    };
 
-    // run it
-    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
-    println!("listening on {}", addr);
-    axum::Server::bind(&addr)
+    // An extractor that performs authorization.
+    struct RequireAuth;
+
+    #[async_trait]
+    impl<B> FromRequest<B> for RequireAuth
+    where
+        B: Send,
+    {
+        type Rejection = StatusCode;
+
+        async fn from_request(req: &mut RequestParts<B>) -> Result<Self, Self::Rejection> {
+            let auth_header = req
+                .headers()
+                .and_then(|headers| headers.get(axum::http::header::AUTHORIZATION))
+                .and_then(|value| value.to_str().ok());
+
+            if let Some(value) = auth_header {
+                if value == "secret" {
+                    return Ok(Self);
+                }
+            }
+
+            Err(StatusCode::UNAUTHORIZED)
+        }
+    }
+
+    async fn handler() {
+        // If we get here the request has been authorized
+    }
+
+    async fn other_handler() {
+        // If we get here the request has been authorized
+    }
+
+    let app = Router::new()
+        .route("/", get(handler))
+        .route("/foo", post(other_handler))
+        // The extractor will run before all routes
+        .layer(extractor_middleware::<RequireAuth>());
+
+    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
         .serve(app.into_make_service())
         .await
         .unwrap();
 }
-
-async fn handler() -> Html<&'static str> {
-    Html("<h1>Hello, World!</h1>")
-}

examples/sse/src/main.rs

@@ -9,7 +9,7 @@ use axum::{
     extract::TypedHeader,
     http::StatusCode,
     response::sse::{Event, Sse},
-    routing::{get, service_method_router as service},
+    routing::{get, service_method_routing as service},
     Router,
 };
 use futures::stream::{self, Stream};

examples/static-file-server/src/main.rs

@@ -5,7 +5,7 @@
 //! ```
 
 use axum::{
-    error_handling::HandleErrorExt, http::StatusCode, routing::service_method_router as service,
+    error_handling::HandleErrorExt, http::StatusCode, routing::service_method_routing as service,
     Router,
 };
 use std::net::SocketAddr;

examples/websockets/src/main.rs

@@ -14,7 +14,7 @@ use axum::{
     },
     http::StatusCode,
     response::IntoResponse,
-    routing::{get, service_method_router as service},
+    routing::{get, service_method_routing as service},
     Router,
 };
 use std::net::SocketAddr;