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.

CHANGELOG.md

@@ -54,12 +54,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ([#405])
   - **breaking:** Method routing for services have been moved from `axum::service`
     to `axum::routing`. So `axum::service::get` now lives at, etc.
-    `axum::routing::service_method_router::get`, etc. ([#405])
+    `axum::routing::service_method_routing::get`, etc. ([#405])
   - **breaking:** `Router::or` renamed to `Router::merge` and will now panic on
     overlapping routes. It now only accepts `Router`s and not general `Service`s.
     Use `Router::fallback` for adding fallback routes ([#408])
   - **added:** `Router::fallback` for adding handlers for request that didn't
-    match any routes ([#408])
+    match any routes. `Router::fallback` must be use instead of `nest("/", _)` ([#408])
   - **breaking:** `EmptyRouter` has been renamed to `MethodNotAllowed` as its only
     used in method routers and not in path routers (`Router`)
   - **breaking:** Remove support for routing based on the `CONNECT` method. An
@@ -119,7 +119,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     use axum::{
         Router, service,
         body::Body,
-        routing::service_method_router::get,
+        routing::service_method_routing::get,
         response::IntoResponse,
         http::{Request, Response},
         error_handling::HandleErrorExt, // for `.handle_error`

Cargo.toml

@@ -62,6 +62,7 @@ tokio = { version = "1.6.1", features = ["macros", "rt", "rt-multi-thread", "net
 tokio-stream = "0.1"
 tracing = "0.1"
 uuid = { version = "0.8", features = ["serde", "v4"] }
+anyhow = "1.0"
 
 [dev-dependencies.tower]
 package = "tower"

README.md

@@ -25,9 +25,13 @@ applications written using [`hyper`] or [`tonic`].
 
 ## Usage example
 
+Note this example uses `main` which contains breaking changes. See the
+[v0.2.x](https://github.com/tokio-rs/axum/tree/v0.2.x) branch for an example
+using 0.2.
+
 ```rust
 use axum::{
-    handler::{get, post},
+    routing::{get, post},
     http::StatusCode,
     response::IntoResponse,
     Json, Router,

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,
+    };
+
+    // 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)
+        }
+    }
 
-    // run it
-    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
-    println!("listening on {}", addr);
-    axum::Server::bind(&addr)
+    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;