From 97adadd9e1790f1bc73b65f57f0471e154e19c37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sun, 21 Apr 2019 19:56:20 +0400
Subject: [PATCH] :memo: Add docs for middleware (#173)

---
 docs/src/middleware/tutorial001.py | 15 +++++++++
 docs/tutorial/middleware.md        | 54 ++++++++++++++++++++++++++++++
 mkdocs.yml                         |  1 +
 3 files changed, 70 insertions(+)
 create mode 100644 docs/src/middleware/tutorial001.py
 create mode 100644 docs/tutorial/middleware.md

diff --git a/docs/src/middleware/tutorial001.py b/docs/src/middleware/tutorial001.py
new file mode 100644
index 000000000..d590cbcf4
--- /dev/null
+++ b/docs/src/middleware/tutorial001.py
@@ -0,0 +1,15 @@
+import time
+
+from fastapi import FastAPI
+from starlette.requests import Request
+
+app = FastAPI()
+
+
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    process_time = time.time() - start_time
+    response.headers["X-Process-Time"] = str(process_time)
+    return response
diff --git a/docs/tutorial/middleware.md b/docs/tutorial/middleware.md
new file mode 100644
index 000000000..f7d0adf47
--- /dev/null
+++ b/docs/tutorial/middleware.md
@@ -0,0 +1,54 @@
+You can add middleware to **FastAPI** applications.
+
+A "middleware" is a function that works with every **request** before it is processed by any specific *path operation*. And also with every **response** before returning it.
+
+* It takes each **request** that comes to your application.
+* It can then do something to that **request** or run any needed code.
+* Then it passes the **request** to be processed by the rest of the application (by some *path operation*).
+* It then takes the **response** generated by the application (by some *path operation*).
+* It can do something to that **response** or run any needed code.
+* Then it returns the **response**.
+
+## Create a middleware
+
+To create a middleware you use the decorator `@app.middleware("http")` on top of a function.
+
+The middleware function receives:
+
+* The `request`.
+* A function `call_next` that will receive the `request` as a parameter.
+    * This function will pass the `request` to the corresponding *path operation*.
+    * Then it returns the `response` generated by the corresponding *path operation*.
+* You can then modify further the `response` before returning it.
+
+```Python hl_lines="9 10 12 15"
+{!./src/middleware/tutorial001.py!}
+```
+
+!!! tip
+    This technique is used in the tutorial about <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">SQL (Relational) Databases</a>.
+
+### Before and after the `response`
+
+You can add code to be run with the `request`,  before any *path operation* receives it. 
+
+And also after the `response` is generated, before returning it.
+
+For example, you could add a custom header `X-Process-Time` containing the time in seconds that it took to process the request and generate a response:
+
+```Python hl_lines="11 13 14"
+{!./src/middleware/tutorial001.py!}
+```
+
+## Starlette's Middleware
+
+You can also add any other <a href="https://www.starlette.io/middleware/" target="_blank">Starlette Middleware</a>.
+
+These are classes instead of plain functions.
+
+Including:
+
+* `CORSMiddleware` (described in the next section).
+* `GZipMiddleware`.
+* `SentryMiddleware`.
+* ...and others.
diff --git a/mkdocs.yml b/mkdocs.yml
index 82d672bd4..7d7c1460a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -58,6 +58,7 @@ nav:
             - Simple OAuth2 with Password and Bearer: 'tutorial/security/simple-oauth2.md'
             - OAuth2 with Password (and hashing), Bearer with JWT tokens: 'tutorial/security/oauth2-jwt.md'
             - OAuth2 scopes: 'tutorial/security/oauth2-scopes.md'
+        - Middleware: 'tutorial/middleware.md'    
         - CORS (Cross-Origin Resource Sharing): 'tutorial/cors.md'    
         - Using the Request Directly: 'tutorial/using-request-directly.md'    
         - SQL (Relational) Databases: 'tutorial/sql-databases.md'