Add readme example project (#450)

* Add project based on the readme example

* Add readme project link to README.md

* Typo correction

* Update examples/readme-example/Cargo.toml

Use tracing-subscriber 0.2 to match other the other examples

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

* Update README.md

Use original readme phrasing for crate docs

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

* Rename readme-exmaple to readme

* Revert tracing call to debug from info

Co-authored-by: Jordan Gould <jordan@tineye.com>
Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

README.md

@@ -92,6 +92,8 @@ struct User {
 }
 ```
 
+You can find this [example][readme-example] as well as other example projects in the [example directory][examples].
+
 See the [crate documentation][docs] for way more examples.
 
 ## Performance
@@ -136,6 +138,7 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in `axum` by you, shall be licensed as MIT, without any
 additional terms or conditions.
 
+[readme-example]: https://github.com/tokio-rs/axum/tree/main/examples/readme-example
 [examples]: https://github.com/tokio-rs/axum/tree/main/examples
 [docs]: https://docs.rs/axum
 [`tower`]: https://crates.io/crates/tower

examples/readme/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "example-readme"
+version = "0.1.0"
+edition = "2018"
+publish = false
+
+[dependencies]
+axum = { path = "../.." }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.68"
+tokio = { version = "1.0", features = ["full"] }
+tracing = "0.1"
+tracing-subscriber = "0.2"

examples/readme/src/main.rs

@@ -0,0 +1,70 @@
+//! Run with
+//!
+//! ```not_rust
+//! cargo run -p example-readme
+//! ```
+
+use axum::{
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+    Json, Router,
+};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+
+#[tokio::main]
+async fn main() {
+    // initialize tracing
+    tracing_subscriber::fmt::init();
+
+    // build our application with a route
+    let app = Router::new()
+        // `GET /` goes to `root`
+        .route("/", get(root))
+        // `POST /users` goes to `create_user`
+        .route("/users", post(create_user));
+
+    // run our app with hyper
+    // `axum::Server` is a re-export of `hyper::Server`
+    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
+    tracing::debug!("listening on {}", addr);
+    axum::Server::bind(&addr)
+        .serve(app.into_make_service())
+        .await
+        .unwrap();
+}
+
+// basic handler that responds with a static string
+async fn root() -> &'static str {
+    "Hello, World!"
+}
+
+async fn create_user(
+    // this argument tells axum to parse the request body
+    // as JSON into a `CreateUser` type
+    Json(payload): Json<CreateUser>,
+) -> impl IntoResponse {
+    // insert your application logic here
+    let user = User {
+        id: 1337,
+        username: payload.username,
+    };
+
+    // this will be converted into a JSON response
+    // with a status code of `201 Created`
+    (StatusCode::CREATED, Json(user))
+}
+
+// the input to our `create_user` handler
+#[derive(Deserialize)]
+struct CreateUser {
+    username: String,
+}
+
+// the output to our `create_user` handler
+#[derive(Serialize)]
+struct User {
+    id: u64,
+    username: String,
+}