:sparkles: Docs and tests, responses with headers and cookies (#185)

diff --git a/docs/src/response_cookies/tutorial001.py b/docs/src/response_cookies/tutorial001.py
new file mode 100644 (file)
index 0000000..badc2fc
--- /dev/null
+++ b/docs/src/response_cookies/tutorial001.py
@@ -0,0 +1,12 @@
+from fastapi import FastAPI
+from starlette.responses import JSONResponse
+
+app = FastAPI()
+
+
+@app.post("/cookie/")
+def create_cookie():
+    content = {"message": "Come to the dark side, we have cookies"}
+    response = JSONResponse(content=content)
+    response.set_cookie(key="fakesession", value="fake-cookie-session-value")
+    return response

diff --git a/docs/src/response_headers/tutorial001.py b/docs/src/response_headers/tutorial001.py
new file mode 100644 (file)
index 0000000..8aad084
--- /dev/null
+++ b/docs/src/response_headers/tutorial001.py
@@ -0,0 +1,11 @@
+from fastapi import FastAPI
+from starlette.responses import JSONResponse
+
+app = FastAPI()
+
+
+@app.get("/headers/")
+def get_headers():
+    content = {"message": "Hello World"}
+    headers = {"X-Cat-Dog": "alone in the world", "Content-Language": "en-US"}
+    return JSONResponse(content=content, headers=headers)

diff --git a/docs/tutorial/middleware.md b/docs/tutorial/middleware.md
index f7d0adf47681cf8e696d33588a03cac96a88a9e2..f3a904d619a9b7dbeba500fd2fe4419f48544eec 100644 (file)
--- a/docs/tutorial/middleware.md
+++ b/docs/tutorial/middleware.md
@@ -28,6 +28,12 @@ The middleware function receives:
 !!! tip
     This technique is used in the tutorial about <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">SQL (Relational) Databases</a>.
 
+
+!!! tip
+    Have in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" target="_blank">using the 'X-' prefix</a>.
+
+    But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <a href="https://fastapi.tiangolo.com/tutorial/cors/" target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <a href="https://www.starlette.io/middleware/#corsmiddleware" target="_blank">Starlette's CORS docs</a>.
+
 ### Before and after the `response`
 
 You can add code to be run with the `request`,  before any *path operation* receives it. 

diff --git a/docs/tutorial/response-cookies.md b/docs/tutorial/response-cookies.md
new file mode 100644 (file)
index 0000000..c36587c
--- /dev/null
+++ b/docs/tutorial/response-cookies.md
@@ -0,0 +1,13 @@
+You can create (set) Cookies in your response.
+
+To do that, you can create a response as described in <a href="https://fastapi.tiangolo.com/tutorial/response-directly/" target="_blank">Return a Response directly</a>.
+
+Then set Cookies in it, and then return it:
+
+```Python hl_lines="10 11 12"
+{!./src/response_cookies/tutorial001.py!}
+```
+
+## More info
+
+To see all the available parameters and options, check the <a href="https://www.starlette.io/responses/#set-cookie" target="_blank">documentation in Starlette</a>.

diff --git a/docs/tutorial/response-headers.md b/docs/tutorial/response-headers.md
new file mode 100644 (file)
index 0000000..b7b1c55
--- /dev/null
+++ b/docs/tutorial/response-headers.md
@@ -0,0 +1,12 @@
+You can add headers to your response.
+
+Create a response as described in <a href="https://fastapi.tiangolo.com/tutorial/response-directly/" target="_blank">Return a Response directly</a> and pass the headers as an additional parameter:
+
+```Python hl_lines="10 11 12"
+{!./src/response_headers/tutorial001.py!}
+```
+
+!!! tip
+    Have in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" target="_blank">using the 'X-' prefix</a>.
+
+    But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <a href="https://fastapi.tiangolo.com/tutorial/cors/" target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <a href="https://www.starlette.io/middleware/#corsmiddleware" target="_blank">Starlette's CORS docs</a>.

diff --git a/mkdocs.yml b/mkdocs.yml
index b53936384be3f99796f1793f72974878ba765008..57712ec12c1c0af200b35ec8b82cacd51f25d2a3 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,6 +48,8 @@ nav:
         - Return a Response directly: 'tutorial/response-directly.md'
         - Custom Response Class: 'tutorial/custom-response.md'
         - Additional Responses in OpenAPI: 'tutorial/additional-responses.md'
+        - Response Cookies: 'tutorial/response-cookies.md'
+        - Response Headers: 'tutorial/response-headers.md'
         - Dependencies:
             - First Steps: 'tutorial/dependencies/first-steps.md'
             - Classes as Dependencies: 'tutorial/dependencies/classes-as-dependencies.md'

diff --git a/tests/test_tutorial/test_response_cookies/__init__.py b/tests/test_tutorial/test_response_cookies/__init__.py
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/tests/test_tutorial/test_response_cookies/test_tutorial001.py b/tests/test_tutorial/test_response_cookies/test_tutorial001.py
new file mode 100644 (file)
index 0000000..f670919
--- /dev/null
+++ b/tests/test_tutorial/test_response_cookies/test_tutorial001.py
@@ -0,0 +1,12 @@
+from starlette.testclient import TestClient
+
+from response_cookies.tutorial001 import app
+
+client = TestClient(app)
+
+
+def test_path_operation():
+    response = client.post("/cookie/")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Come to the dark side, we have cookies"}
+    assert response.cookies["fakesession"] == "fake-cookie-session-value"

diff --git a/tests/test_tutorial/test_response_headers/__init__.py b/tests/test_tutorial/test_response_headers/__init__.py
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/tests/test_tutorial/test_response_headers/test_tutorial001.py b/tests/test_tutorial/test_response_headers/test_tutorial001.py
new file mode 100644 (file)
index 0000000..9a3d172
--- /dev/null
+++ b/tests/test_tutorial/test_response_headers/test_tutorial001.py
@@ -0,0 +1,13 @@
+from starlette.testclient import TestClient
+
+from response_headers.tutorial001 import app
+
+client = TestClient(app)
+
+
+def test_path_operation():
+    response = client.get("/headers/")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello World"}
+    assert response.headers["X-Cat-Dog"] == "alone in the world"
+    assert response.headers["Content-Language"] == "en-US"