Improve json documentation (#245)

Co-authored-by: Rob Ede <robjtede@icloud.com>

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]

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

examples/responses/src/json_resp.rs

@@ -1,17 +1,18 @@
 // <json-resp>
-use actix_web::{get, web, HttpResponse, Result};
+use actix_web::{get, web, Responder, Result};
-use serde::{Deserialize, Serialize};
+use serde::Serialize;
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize)]
 struct MyObj {
     name: String,
 }
 
 #[get("/a/{name}")]
-async fn index(obj: web::Path<MyObj>) -> Result<HttpResponse> {
+async fn index(name: web::Path<String>) -> Result<impl Responder> {
-    Ok(HttpResponse::Ok().json(MyObj {
+    let obj = MyObj {
-        name: obj.name.to_string(),
+        name: name.to_string(),
-    }))
+    };
+    Ok(web::Json(obj))
 }
 
 #[actix_web::main]