:sparkles: Add docs about responses with additional status codes (#156)

* :sparkles: Add docs about responses with additional status codes

* :memo: Update docs, link to documenting additional responses

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 6e5ee8d028fda1d99728a535e31233afb154326e..c285767e9024c7d6f16170a95c8fdbf85f147bc2 100644 (file)
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,5 +1,7 @@
 ## Next release
 
+* Add docs for: <a href="https://fastapi.tiangolo.com/tutorial/additional-status-codes/" target="_blank">Additional Status Codes</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/156" target="_blank">#156</a>.
+
 ## 0.14.0
 
 * Improve automatically generated names of path operations in OpenAPI (in API docs). A function `read_items` instead of having a generated name "Read Items Get" will have "Read Items". PR <a href="https://github.com/tiangolo/fastapi/pull/155" target="_blank">#155</a>.

diff --git a/docs/src/additional_status_codes/tutorial001.py b/docs/src/additional_status_codes/tutorial001.py
new file mode 100644 (file)
index 0000000..d329786
--- /dev/null
+++ b/docs/src/additional_status_codes/tutorial001.py
@@ -0,0 +1,20 @@
+from fastapi import Body, FastAPI
+from starlette.responses import JSONResponse
+from starlette.status import HTTP_201_CREATED
+
+app = FastAPI()
+
+items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}
+
+
+@app.put("/items/{item_id}")
+async def upsert_item(item_id: str, name: str = Body(None), size: int = Body(None)):
+    if item_id in items:
+        item = items[item_id]
+        item["name"] = name
+        item["size"] = size
+        return item
+    else:
+        item = {"name": name, "size": size}
+        items[item_id] = item
+        return JSONResponse(status_code=HTTP_201_CREATED, content=item)

diff --git a/docs/tutorial/additional-status-codes.md b/docs/tutorial/additional-status-codes.md
new file mode 100644 (file)
index 0000000..88b633a
--- /dev/null
+++ b/docs/tutorial/additional-status-codes.md
@@ -0,0 +1,30 @@
+By default, **FastAPI** will return the responses using Starlette's `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.
+
+It will use the default status code or the one you set in your *path operation*.
+
+## Additional status codes
+
+If you want to return additional status codes apart from the main one, you can do that by returning a `Response` directly, like a `JSONResponse`, and set the additional status code directly.
+
+For example, let's say that you want to have a *path operation* that allows to update items, and returns HTTP status codes of 200 "OK" when successful.
+
+But you also want it to accept new items. And when the items didn't exist before, it creates them, and returns an HTTP status code of 201 "Created".
+
+To achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want:
+
+```Python hl_lines="2 20"
+{!./src/additional_status_codes/tutorial001.py!}
+```
+
+!!! warning
+    When you return a `Response` directly, like in the example above, it will be returned directly.
+
+    It won't be serialized with a model, etc.
+    
+    Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).
+
+## OpenAPI and API docs
+
+If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know before hand what you are going to return.
+
+But you can document that in your code, using: <a href="https://fastapi.tiangolo.com/tutorial/additional-responses/" target="_blank">Additional Responses</a>.
\ No newline at end of file

diff --git a/mkdocs.yml b/mkdocs.yml
index ef463f38bcb0052c0efde482e16bb936d06cf0b7..99f313e55b62ba433aab0398b47c7dbf0080f378 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,6 +43,7 @@ nav:
         - Handling Errors: 'tutorial/handling-errors.md'
         - Path Operation Configuration: 'tutorial/path-operation-configuration.md'
         - Path Operation Advanced Configuration: 'tutorial/path-operation-advanced-configuration.md'
+        - Additional Status Codes: 'tutorial/additional-status-codes.md'
         - Custom Response: 'tutorial/custom-response.md'
         - Additional Responses: 'tutorial/additional-responses.md'
         - Dependencies:

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

diff --git a/tests/test_tutorial/test_additional_status_codes/test_tutorial001.py b/tests/test_tutorial/test_additional_status_codes/test_tutorial001.py
new file mode 100644 (file)
index 0000000..1d33796
--- /dev/null
+++ b/tests/test_tutorial/test_additional_status_codes/test_tutorial001.py
@@ -0,0 +1,17 @@
+from starlette.testclient import TestClient
+
+from additional_status_codes.tutorial001 import app
+
+client = TestClient(app)
+
+
+def test_update():
+    response = client.put("/items/foo", json={"name": "Wrestlers"})
+    assert response.status_code == 200
+    assert response.json() == {"name": "Wrestlers", "size": None}
+
+
+def test_create():
+    response = client.put("/items/red", json={"name": "Chillies"})
+    assert response.status_code == 201
+    assert response.json() == {"name": "Chillies", "size": None}