:memo: Add docs for using the Starlette Request directly (#25)

Add docs for using the Starlette Request directly

diff --git a/docs/src/using_request_directly/tutorial001.py b/docs/src/using_request_directly/tutorial001.py
new file mode 100644 (file)
index 0000000..ca71f32
--- /dev/null
+++ b/docs/src/using_request_directly/tutorial001.py
@@ -0,0 +1,10 @@
+from fastapi import FastAPI
+from starlette.requests import Request
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+def read_root(item_id: str, request: Request):
+    client_host = request.client.host
+    return {"client_host": client_host, "item_id": item_id}

diff --git a/docs/tutorial/extra-starlette.md b/docs/tutorial/extra-starlette.md
deleted file mode 100644 (file)
index fdf702f..0000000
--- a/docs/tutorial/extra-starlette.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon...
\ No newline at end of file

diff --git a/docs/tutorial/using-request-directly.md b/docs/tutorial/using-request-directly.md
new file mode 100644 (file)
index 0000000..fe4f93b
--- /dev/null
+++ b/docs/tutorial/using-request-directly.md
@@ -0,0 +1,55 @@
+Up to now, you have been declaring the parts of the request that you need with their types.
+
+Taking data from:
+
+* The path as parameters.
+* Headers.
+* Cookies.
+* etc.
+
+And by doing so, **FastAPI** is validating that data, converting it and generating documentation for your API automatically.
+
+But there are situations where you might need to access the `Request` object directly.
+
+## Details about the `Request` object
+
+As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <a href="https://www.starlette.io/requests/" target="_blank">`Request`</a> object directly when you need to.
+
+It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or annotated (with OpenAPI, for the automatic documentation) by FastAPI.
+
+Although any other parameter declared normally (for example, the body with a Pydantic model) would still be validated, converted, annotated, etc.
+
+But there are specific cases where it's useful to get the `Request` object.
+
+## Use the `Request` object direclty
+
+Let's imagine you want to get the client's IP address/host inside of your *path operation function*.
+
+For that you need to access the request directly.
+
+### Import the `Request`
+
+First, import the `Request` class from Starlette:
+
+```Python hl_lines="2"
+{!./src/using_request_directly/tutorial001.py!}
+```
+
+### Declare the `Request` parameter
+
+Then declare a *path operation function* parameter with the type being the `Request` class:
+
+```Python hl_lines="8"
+{!./src/using_request_directly/tutorial001.py!}
+```
+
+!!! tip
+    Note that in this case, we are declaring a path parameter besides the request parameter.
+
+    So, the path parameter will be extracted, validated, converted to the specified type and annotated with OpenAPI.
+
+    The same way, you can declare any other parameter as normally, and additionally, get the `Request` too.
+
+## `Request` documentation
+
+You can read more details about the <a href="https://www.starlette.io/requests/" target="_blank">`Request` object in the official Starlette documentation site</a>.

diff --git a/mkdocs.yml b/mkdocs.yml
index 397a21d9c2519530177fc14a470adfbbe46b4e07..ac7abfc504f9378e6222e446f6931d46b903cea4 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,12 +54,12 @@ nav:
             - Get Current User: 'tutorial/security/get-current-user.md'
             - 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'
+        - Using the Request Directly: 'tutorial/using-request-directly.md'    
         - SQL (Relational) Databases: 'tutorial/sql-databases.md'
         - NoSQL (Distributed / Big Data) Databases: 'tutorial/nosql-databases.md'
         - Bigger Applications - Multiple Files: 'tutorial/bigger-applications.md'
         - Sub Applications - Behind a Proxy: 'tutorial/sub-applications-proxy.md'
         - Application Configuration: 'tutorial/application-configuration.md'
-        - Extra Starlette options: 'tutorial/extra-starlette.md'    
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'
     - Project Generation - Template: 'project-generation.md'