migrate to docusaurus (v2) (#266)

Co-authored-by: ibraheemdev <ibrah1440@gmail.com>

docs/handlers.md

@@ -0,0 +1,70 @@
+---
+title: Handlers
+---
+
+import CodeBlock from "@site/src/components/code_block.js";
+
+# Request Handlers
+
+A request handler is an async function that accepts zero or more parameters that can be extracted from a request (i.e., [_impl FromRequest_][implfromrequest]) and returns a type that can be converted into an HttpResponse (i.e., [_impl Responder_][respondertrait]).
+
+Request handling happens in two stages. First the handler object is called, returning any object that implements the [_Responder_][respondertrait] trait. Then, `respond_to()` is called on the returned object, converting itself to a `HttpResponse` or `Error`.
+
+By default actix-web provides `Responder` implementations for some standard types, such as `&'static str`, `String`, etc.
+
+> For a complete list of implementations, check the [_Responder documentation_][responderimpls].
+
+Examples of valid handlers:
+
+```rust
+async fn index(_req: HttpRequest) -> &'static str {
+    "Hello world!"
+}
+```
+
+```rust
+async fn index(_req: HttpRequest) -> String {
+    "Hello world!".to_owned()
+}
+```
+
+You can also change the signature to return `impl Responder` which works well if more complex types are involved.
+
+```rust
+async fn index(_req: HttpRequest) -> impl Responder {
+    web::Bytes::from_static(b"Hello world!")
+}
+```
+
+```rust
+async fn index(req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
+    ...
+}
+```
+
+## Response with custom type
+
+To return a custom type directly from a handler function, the type needs to implement the `Responder` trait.
+
+Let's create a response for a custom type that serializes to an `application/json` response:
+
+<CodeBlock example="responder-trait" file="main.rs" section="responder-trait" />
+
+## Streaming response body
+
+Response body can be generated asynchronously. In this case, body must implement the stream trait `Stream<Item=Bytes, Error=Error>`, i.e.:
+
+<CodeBlock example="async-handlers" file="stream.rs" section="stream" />
+
+## Different return types (Either)
+
+Sometimes, you need to return different types of responses. For example, you can error check and return errors, return async responses, or any result that requires two different types.
+
+For this case, the [Either][either] type can be used. `Either` allows combining two different responder types into a single type.
+
+<CodeBlock example="either" file="main.rs" section="either" />
+
+[implfromrequest]: https://docs.rs/actix-web/4/actix_web/trait.FromRequest.html
+[respondertrait]: https://docs.rs/actix-web/4/actix_web/trait.Responder.html
+[responderimpls]: https://docs.rs/actix-web/4/actix_web/trait.Responder.html#foreign-impls
+[either]: https://docs.rs/actix-web/4/actix_web/enum.Either.html