From c66502c5482e4ce3d2fd85592acf7547aadaa84e Mon Sep 17 00:00:00 2001
From: nikstur <61635709+nikstur@users.noreply.github.com>
Date: Sun, 5 Dec 2021 15:41:37 +0100
Subject: [PATCH] Improve json documentation (#245)

Co-authored-by: Rob Ede <robjtede@icloud.com>
---
 content/docs/request.md             | 28 ++++++++++++----------------
 content/docs/response.md            | 26 ++++++++++++++++++--------
 examples/responses/src/json_resp.rs | 15 ++++++++-------
 3 files changed, 38 insertions(+), 31 deletions(-)

diff --git a/content/docs/request.md b/content/docs/request.md
index 88e48f0..21700c9 100644
--- a/content/docs/request.md
+++ b/content/docs/request.md
@@ -4,22 +4,6 @@ menu: docs_advanced
 weight: 200
 ---
 
-# Content Encoding
-
-Actix-web automatically *decompresses* payloads. The following codecs are supported:
-
-* Brotli
-* Chunked
-* Compress
-* Gzip
-* Deflate
-* Identity
-* Trailers
-* EncodingExt
-
-If request headers contain a `Content-Encoding` header, the request payload is decompressed
-according to the header value. Multiple codecs are not supported, i.e: `Content-Encoding: br, gzip`.
-
 # JSON Request
 
 There are several options for json body deserialization.
@@ -53,6 +37,18 @@ body first and then deserialize the json into an object.
 
 > A complete example for both options is available in [examples directory][examples].
 
+# Content Encoding
+
+Actix-web automatically *decompresses* payloads. The following codecs are supported:
+
+* Brotli
+* Gzip
+* Deflate
+* Zstd
+
+If request headers contain a `Content-Encoding` header, the request payload is decompressed
+according to the header value. Multiple codecs are not supported, i.e: `Content-Encoding: br, gzip`.
+
 # Chunked transfer encoding
 
 Actix automatically decodes *chunked* encoding. The [`web::Payload`][payloadextractor]
diff --git a/content/docs/response.md b/content/docs/response.md
index c90b4f2..77e1d30 100644
--- a/content/docs/response.md
+++ b/content/docs/response.md
@@ -18,6 +18,24 @@ instance multiple times, the builder will panic.
 
 {{< include-example example="responses" file="main.rs" section="builder" >}}
 
+# JSON Response
+
+The `Json` type allows to respond with well-formed JSON data: simply return a value of
+type `Json<T>` where `T` is the type of a structure to serialize into *JSON*.
+The type `T` must implement the `Serialize` trait from *serde*.
+
+For the following example to work, you need to add `serde` to your dependencies in `Cargo.toml`:
+
+```toml
+[dependencies]
+serde = "1"
+```
+
+{{< include-example example="responses" file="json_resp.rs" section="json-resp" >}}
+
+Using the `Json` type this way instead of calling the `.json` method on a `HttpResponse` makes it
+immediately clear that the function returns JSON and not any other type of response.
+
 # Content encoding
 
 Actix-web can automatically *compress* payloads with the [*Compress middleware*][compressmidddleware].
@@ -63,13 +81,5 @@ negotiation.
 
 {{< include-example example="responses" file="auto.rs" section="auto" >}}
 
-# JSON Response
-
-The `Json` type allows to respond with well-formed JSON data: simply return a value of
-type `Json<T>` where `T` is the type of a structure to serialize into *JSON*.
-The type `T` must implement the `Serialize` trait from *serde*.
-
-{{< include-example example="responses" file="json_resp.rs" section="json-resp" >}}
-
 [responsebuilder]: https://docs.rs/actix-web/3/actix_web/dev/struct.HttpResponseBuilder.html
 [compressmidddleware]: https://docs.rs/actix-web/3/actix_web/middleware/struct.Compress.html
diff --git a/examples/responses/src/json_resp.rs b/examples/responses/src/json_resp.rs
index b460a50..d991038 100644
--- a/examples/responses/src/json_resp.rs
+++ b/examples/responses/src/json_resp.rs
@@ -1,17 +1,18 @@
 // <json-resp>
-use actix_web::{get, web, HttpResponse, Result};
-use serde::{Deserialize, Serialize};
+use actix_web::{get, web, Responder, Result};
+use serde::Serialize;
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize)]
 struct MyObj {
     name: String,
 }
 
 #[get("/a/{name}")]
-async fn index(obj: web::Path<MyObj>) -> Result<HttpResponse> {
-    Ok(HttpResponse::Ok().json(MyObj {
-        name: obj.name.to_string(),
-    }))
+async fn index(name: web::Path<String>) -> Result<impl Responder> {
+    let obj = MyObj {
+        name: name.to_string(),
+    };
+    Ok(web::Json(obj))
 }
 
 #[actix_web::main]