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

* ✨ Add docs about responses with additional status codes

* 📝 Update docs, link to documenting additional responses

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>.

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)

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>.

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:

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}