🔖 Release 0.12.1, fix responses in include_router

Add additional responses to OpenAPI, including Pydantic models or schemas directly, custom status codes, media types, extending `response_model`, etc.

docs/release-notes.md

@@ -1,5 +1,23 @@
 ## Next release
 
+## 0.12.1
+
+* Fix bug: handling additional `responses` in `APIRouter.include_router()`. PR <a href="https://github.com/tiangolo/fastapi/pull/140" target="_blank">#140</a>.
+
+* Fix typo in SQL tutorial. PR <a href="https://github.com/tiangolo/fastapi/pull/138" target="_blank">#138</a> by <a href="https://github.com/mostaphaRoudsari" target="_blank">@mostaphaRoudsari</a>.
+
+* Fix typos in section about nested models and OAuth2 with JWT. PR <a href="https://github.com/tiangolo/fastapi/pull/127" target="_blank">#127</a> by <a href="https://github.com/mmcloud" target="_blank">@mmcloud</a>.
+
+## 0.12.0
+
+* Add additional `responses` parameter to *path operation decorators* to extend responses in OpenAPI (and API docs).
+    * It also allows extending existing responses generated from `response_model`, declare other media types (like images), etc.
+    * The new documentation is here: <a href="https://fastapi.tiangolo.com/tutorial/additional-responses/" target="_blank">Additional Responses</a>.
+    * `responses` can also be added to `.include_router()`, the updated docs are here: <a href="https://fastapi.tiangolo.com/tutorial/bigger-applications/#add-some-custom-tags-and-responses" target="_blank">Bigger Applications</a>.
+    * PR <a href="https://github.com/tiangolo/fastapi/pull/97" target="_blank">#97</a> originally initiated by <a href="https://github.com/barsi" target="_blank">@barsi</a>.
+
+* Update `scripts/test-cov-html.sh` to allow passing extra parameters like `-vv`, for development.
+
 ## 0.11.0
 
 * Add `auto_error` parameter to security utility functions. Allowing them to be optional. Also allowing to have multiple alternative security schemes that are then checked in a single dependency instead of each one verifying and returning the error to the client automatically when not satisfied. PR <a href="https://github.com/tiangolo/fastapi/pull/134" target="_blank">#134</a>.

docs/src/additional_responses/tutorial001.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+
+class Item(BaseModel):
+    id: str
+    value: str
+
+
+class Message(BaseModel):
+    message: str
+
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}", response_model=Item, responses={404: {"model": Message}})
+async def read_item(item_id: str):
+    if item_id == "foo":
+        return {"id": "foo", "value": "there goes my hero"}
+    else:
+        return JSONResponse(status_code=404, content={"message": "Item not found"})

docs/src/additional_responses/tutorial002.py

@@ -0,0 +1,28 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from starlette.responses import FileResponse
+
+
+class Item(BaseModel):
+    id: str
+    value: str
+
+
+app = FastAPI()
+
+
+@app.get(
+    "/items/{item_id}",
+    response_model=Item,
+    responses={
+        200: {
+            "content": {"image/png": {}},
+            "description": "Return the JSON item or an image.",
+        }
+    },
+)
+async def read_item(item_id: str, img: bool = None):
+    if img:
+        return FileResponse("image.png", media_type="image/png")
+    else:
+        return {"id": "foo", "value": "there goes my hero"}

docs/src/additional_responses/tutorial003.py

@@ -0,0 +1,37 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+
+class Item(BaseModel):
+    id: str
+    value: str
+
+
+class Message(BaseModel):
+    message: str
+
+
+app = FastAPI()
+
+
+@app.get(
+    "/items/{item_id}",
+    response_model=Item,
+    responses={
+        404: {"model": Message, "description": "The item was not found"},
+        200: {
+            "description": "Item requested by ID",
+            "content": {
+                "application/json": {
+                    "example": {"id": "bar", "value": "The bar tenders"}
+                }
+            },
+        },
+    },
+)
+async def read_item(item_id: str):
+    if item_id == "foo":
+        return {"id": "foo", "value": "there goes my hero"}
+    else:
+        return JSONResponse(status_code=404, content={"message": "Item not found"})

docs/src/additional_responses/tutorial004.py

@@ -0,0 +1,30 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from starlette.responses import FileResponse
+
+
+class Item(BaseModel):
+    id: str
+    value: str
+
+
+responses = {
+    404: {"description": "Item not found"},
+    302: {"description": "The item was moved"},
+    403: {"description": "Not enough privileges"},
+}
+
+
+app = FastAPI()
+
+
+@app.get(
+    "/items/{item_id}",
+    response_model=Item,
+    responses={**responses, 200: {"content": {"image/png": {}}}},
+)
+async def read_item(item_id: str, img: bool = None):
+    if img:
+        return FileResponse("image.png", media_type="image/png")
+    else:
+        return {"id": "foo", "value": "there goes my hero"}

docs/src/bigger_applications/app/main.py

@@ -5,4 +5,9 @@ from .routers import items, users
 app = FastAPI()
 
 app.include_router(users.router)
-app.include_router(items.router, prefix="/items", tags=["items"])
+app.include_router(
+    items.router,
+    prefix="/items",
+    tags=["items"],
+    responses={404: {"description": "Not found"}},
+)

docs/src/bigger_applications/app/routers/items.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from fastapi import APIRouter, HTTPException
 
 router = APIRouter()
 
@@ -11,3 +11,14 @@ async def read_items():
 @router.get("/{item_id}")
 async def read_item(item_id: str):
     return {"name": "Fake Specific Item", "item_id": item_id}
+
+
+@router.put(
+    "/{item_id}",
+    tags=["custom"],
+    responses={403: {"description": "Operation forbidden"}},
+)
+async def update_item(item_id: str):
+    if item_id != "foo":
+        raise HTTPException(status_code=403, detail="You can only update the item: foo")
+    return {"item_id": item_id, "name": "The Fighters"}

docs/src/body_nested_models/tutorial005.py

@@ -1,8 +1,7 @@
 from typing import Set
 
 from fastapi import FastAPI
-from pydantic import BaseModel
-from pydantic.types import UrlStr
+from pydantic import BaseModel, UrlStr
 
 app = FastAPI()
 

docs/src/body_nested_models/tutorial006.py

@@ -1,8 +1,7 @@
 from typing import List, Set
 
 from fastapi import FastAPI
-from pydantic import BaseModel
-from pydantic.types import UrlStr
+from pydantic import BaseModel, UrlStr
 
 app = FastAPI()
 
@@ -18,7 +17,7 @@ class Item(BaseModel):
     price: float
     tax: float = None
     tags: Set[str] = []
-    image: List[Image] = None
+    images: List[Image] = None
 
 
 @app.put("/items/{item_id}")

docs/src/body_nested_models/tutorial007.py

@@ -1,8 +1,7 @@
 from typing import List, Set
 
 from fastapi import FastAPI
-from pydantic import BaseModel
-from pydantic.types import UrlStr
+from pydantic import BaseModel, UrlStr
 
 app = FastAPI()
 
@@ -18,7 +17,7 @@ class Item(BaseModel):
     price: float
     tax: float = None
     tags: Set[str] = []
-    image: List[Image] = None
+    images: List[Image] = None
 
 
 class Offer(BaseModel):

docs/src/body_nested_models/tutorial008.py

@@ -1,8 +1,7 @@
 from typing import List
 
 from fastapi import FastAPI
-from pydantic import BaseModel
-from pydantic.types import UrlStr
+from pydantic import BaseModel, UrlStr
 
 app = FastAPI()
 

docs/tutorial/additional-responses.md

@@ -0,0 +1,235 @@
+!!! warning
+    This is a rather advanced topic.
+    
+    If you are starting with **FastAPI**, you might not need this.
+
+You can declare additional responses, with additional status codes, media types, descriptions, etc.
+
+Those additional responses will be included in the OpenAPI schema, so they will also appear in the API docs.
+
+But for those additional responses you have to make sure you return a `Response` like `JSONResponse` directly, with your status code and content.
+
+## Additional Response with `model`
+
+You can pass to your *path operation decorators* a parameter `responses`.
+
+It receives a `dict`, the keys are status codes for each response, like `200`, and the values are other `dict`s with the information for each of them.
+
+Each of those response `dict`s can have a key `model`, containing a Pydantic model, just like `response_model`.
+
+**FastAPI** will take that model, generate its JSON Schema and include it in the correct place in OpenAPI.
+
+For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write:
+
+
+```Python hl_lines="18 23"
+{!./src/additional_responses/tutorial001.py!}
+```
+
+!!! note
+    Have in mind that you have to return the `JSONResponse` directly.
+
+!!! info
+    The `model` key is not part of OpenAPI.
+
+    **FastAPI** will take the Pydantic model from there, generate the `JSON Schema`, and put it in the correct place.
+
+    The correct place is:
+    
+    * In the key `content`, that has as value another JSON object (`dict`) that contains:
+        * A key with the media type, e.g. `application/json`, that contains as value another JSON object, that contains:
+            * A key `schema`, that has as the value the JSON Schema from the model, here's the correct place.
+                * **FastAPI** adds a reference here to the global JSON Schemas in another place in your OpenAPI instead of including it directly. This way, other applications and clients can use those JSON Schemas directly, provide better code generation tools, etc.
+
+The generated responses in the OpenAPI for this *path operation* will be:
+
+```JSON hl_lines="3 4 5 6 7 8 9 10 11 12"
+{
+    "responses": {
+        "404": {
+            "description": "Additional Response",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/Message"
+                    }
+                }
+            }
+        },
+        "200": {
+            "description": "Successful Response",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/Item"
+                    }
+                }
+            }
+        },
+        "422": {
+            "description": "Validation Error",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/HTTPValidationError"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+The schemas are referenced to another place inside the OpenAPI schema:
+
+```JSON hl_lines="4 5 6 7 8 9 10 11 12 13 14 15 16"
+{
+    "components": {
+        "schemas": {
+            "Message": {
+                "title": "Message",
+                "required": [
+                    "message"
+                ],
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "title": "Message",
+                        "type": "string"
+                    }
+                }
+            },
+            "Item": {
+                "title": "Item",
+                "required": [
+                    "id",
+                    "value"
+                ],
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "title": "Id",
+                        "type": "string"
+                    },
+                    "value": {
+                        "title": "Value",
+                        "type": "string"
+                    }
+                }
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": [
+                    "loc",
+                    "msg",
+                    "type"
+                ],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "msg": {
+                        "title": "Message",
+                        "type": "string"
+                    },
+                    "type": {
+                        "title": "Error Type",
+                        "type": "string"
+                    }
+                }
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/ValidationError"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Additional media types for the main response
+
+You can use this same `responses` parameter to add different media types for the same main response.
+
+For example, you can add an additional media type of `image/png`, declaring that your *path operation* can return a JSON object (with media type `application/json`) or a PNG image:
+
+```Python hl_lines="17 18 19 20 21 22 23 24 28"
+{!./src/additional_responses/tutorial002.py!}
+```
+
+!!! note
+    Notice that you have to return the image using a `FileResponse` directly.
+
+## Combining information
+
+You can also combine response information from multiple places, including the `response_model`, `status_code`, and `responses` parameters.
+
+You can declare a `response_model`, using the default status code `200` (or a custom one if you need), and then declare additional information for that same response in `responses`, directly in the OpenAPI schema.
+
+**FastAPI** will keep the additional information from `responses`, and combine it with the JSON Schema from your model.
+
+For example, you can declare a response with a status code `404` that uses a Pydantic model and has a custom `description`.
+
+And a response with a status code `200` that uses your `response_model`, but includes a custom `example`:
+
+```Python hl_lines="20 21 22 23 24 25 26 27 28 29 30 31"
+{!./src/additional_responses/tutorial003.py!}
+```
+
+It will all be combined and included in your OpenAPI, and shown in the API docs:
+
+<img src="/img/tutorial/additional-responses/image01.png">
+
+
+## Combine predefined responses and custom ones
+
+You might want to have some predefined responses that apply to many *path operations*, but you want to combine them with custom responses needed by each *path operation*.
+
+For those cases, you can use the Python technique of "unpacking" a `dict` with `**dict_to_unpack`:
+
+```Python
+old_dict = {
+    "old key": "old value",
+    "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+Here, `new_dict` will contain all the key-value pairs from `old_dict` plus the new key-value pair:
+
+```Python
+{
+    "old key": "old value",
+    "second old key": "second old value",
+    "new key": "new value",
+}
+```
+
+You can use that technique to re-use some predefined responses in your *path operations* and combine them with additional custom ones.
+
+For example:
+
+```Python hl_lines="11 12 13 14 15 24"
+{!./src/additional_responses/tutorial004.py!}
+```
+
+## More information about OpenAPI responses
+
+To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:
+
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject" target="_blank">OpenAPI Responses Object</a>, it includes the `Response Object`.
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject" target="_blank">OpenAPI Response Object</a>, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.

docs/tutorial/bigger-applications.md

@@ -103,7 +103,17 @@ But let's say that this time we are more lazy.
 
 And we don't want to have to explicitly type `/items/` and `tags=["items"]` in every *path operation* (we will be able to do it later):
 
-```Python hl_lines="6 11 16"
+```Python hl_lines="6 11"
+{!./src/bigger_applications/app/routers/items.py!}
+```
+
+### Add some custom `tags` and `responses`
+
+We are not adding the prefix `/items/` nor the `tags=["items"]` to add them later.
+
+But we can add custom `tags` and `responses` that will be applied to a specific *path operation*:
+
+```Python hl_lines="18 19"
 {!./src/bigger_applications/app/routers/items.py!}
 ```
 
@@ -192,7 +202,7 @@ So, to be able to use both of them in the same file, we import the submodules di
 
 Now, let's include the `router` from the submodule `users`:
 
-```Python hl_lines="8"
+```Python hl_lines="7"
 {!./src/bigger_applications/app/main.py!}
 ```
 
@@ -217,7 +227,7 @@ It will include all the routes from that router as part of it.
     So it won't affect performance.
 
 
-### Include an `APIRouter` with a prefix
+### Include an `APIRouter` with a `prefix`, `tags`, and `responses`
 
 Now, let's include the router form the `items` submodule.
 
@@ -237,9 +247,11 @@ async def read_item(item_id: str):
 
 So, the prefix in this case would be `/items`.
 
-And we can also add a list of `tags` that will be applied to all the *path operations* included in this router:
+We can also add a list of `tags` that will be applied to all the *path operations* included in this router.
 
-```Python hl_lines="9"
+And we can add predefined `responses` that will be included in all the *path operations* too.
+
+```Python hl_lines="8 9 10 11 12 13"
 {!./src/bigger_applications/app/main.py!}
 ```
 
@@ -250,12 +262,18 @@ The end result is that the item paths are now:
 
 ...as we intended.
 
-And they are marked with a list of tags that contain a single string `"items"`.
+They will be marked with a list of tags that contain a single string `"items"`.
+
+The *path operation* that declared a `"custom"` tag will have both tags, `items` and `custom`.
 
 These "tags" are especially useful for the automatic interactive documentation systems (using OpenAPI).
 
+And all of them will include the the predefined `responses`.
+
+The *path operation* that declared a custom `403` response will have both the predefined responses (`404`) and the `403` declared in it directly.
+
 !!! check
-    The `prefix` and `tags` parameters are (as in many other cases) just a feature from **FastAPI** to help you avoid code duplication.
+    The `prefix`, `tags`, and `responses` parameters are (as in many other cases) just a feature from **FastAPI** to help you avoid code duplication.
 
 
 !!! tip

docs/tutorial/body-nested-models.md

@@ -120,7 +120,7 @@ To see all the options you have, checkout the docs for <a href="https://pydantic
 
 For example, as in the `Image` model we have a `url` field, we can declare it to be instead of a `str`, a Pydantic's `UrlStr`:
 
-```Python hl_lines="5 11"
+```Python hl_lines="4 10"
 {!./src/body_nested_models/tutorial005.py!}
 ```
 
@@ -130,7 +130,7 @@ The string will be checked to be a valid URL, and documented in JSON Schema / Op
 
 You can also use Pydantic models as subtypes of `list`, `set`, etc:
 
-```Python hl_lines="21"
+```Python hl_lines="20"
 {!./src/body_nested_models/tutorial006.py!}
 ```
 
@@ -167,7 +167,7 @@ This will expect (convert, validate, document, etc) a JSON body like:
 
 You can define arbitrarily deeply nested models:
 
-```Python hl_lines="10 15 21 24 28"
+```Python hl_lines="9 14 20 23 27"
 {!./src/body_nested_models/tutorial007.py!}
 ```
 
@@ -184,7 +184,7 @@ images: List[Image]
 
 as in:
 
-```Python hl_lines="16"
+```Python hl_lines="15"
 {!./src/body_nested_models/tutorial008.py!}
 ```
 

docs/tutorial/security/oauth2-jwt.md

@@ -22,7 +22,7 @@ If you want to play with JWT tokens and see how they work, check <a href="https:
 
 ## Install `PyJWT`
 
-We need to install `PyJWT` to generate and verity the JWT tokens in Python:
+We need to install `PyJWT` to generate and verify the JWT tokens in Python:
 
 ```bash
 pip install pyjwt
@@ -198,7 +198,7 @@ Many packages that simplify it a lot have to make many compromises with the data
 
 **FastAPI** doesn't make any compromise with any database, data model or tool.
 
-It gives you all the flexibility to chose the ones that fit your project the best.
+It gives you all the flexibility to choose the ones that fit your project the best.
 
 And you can use directly many well maintained and widely used packages like `passlib` and `pyjwt`, because **FastAPI** doesn't require any complex mechanisms to integrate external packages.
 

docs/tutorial/sql-databases.md

@@ -86,7 +86,7 @@ This object (class) is not a connection to the database yet, but once we create
 
 We name it `SessionLocal` to distinguish it form the `Session` we are importing from SQLAlchemy.
 
-We will use `Session` to declare types later and getter better editor support and completion.
+We will use `Session` to declare types later and to get better editor support and completion.
 
 For now, create the `SessionLocal`:
 

fastapi/__init__.py

@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.11.0"
+__version__ = "0.12.1"
 
 from starlette.background import BackgroundTasks
 

fastapi/applications.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, Dict, List, Optional, Type
+from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from fastapi import routing
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
@@ -114,6 +114,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         methods: List[str] = None,
         operation_id: str = None,
@@ -130,6 +131,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=methods,
             operation_id=operation_id,
@@ -148,6 +150,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         methods: List[str] = None,
         operation_id: str = None,
@@ -165,6 +168,7 @@ class FastAPI(Starlette):
                 summary=summary,
                 description=description,
                 response_description=response_description,
+                responses=responses or {},
                 deprecated=deprecated,
                 methods=methods,
                 operation_id=operation_id,
@@ -177,9 +181,16 @@ class FastAPI(Starlette):
         return decorator
 
     def include_router(
-        self, router: routing.APIRouter, *, prefix: str = "", tags: List[str] = None
+        self,
+        router: routing.APIRouter,
+        *,
+        prefix: str = "",
+        tags: List[str] = None,
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
     ) -> None:
-        self.router.include_router(router, prefix=prefix, tags=tags)
+        self.router.include_router(
+            router, prefix=prefix, tags=tags, responses=responses or {}
+        )
 
     def get(
         self,
@@ -191,6 +202,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -205,6 +217,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -222,6 +235,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -236,6 +250,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -253,6 +268,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -267,6 +283,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -284,6 +301,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -298,6 +316,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -315,6 +334,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -329,6 +349,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -346,6 +367,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -360,6 +382,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -377,6 +400,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -391,6 +415,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,
@@ -408,6 +433,7 @@ class FastAPI(Starlette):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -422,6 +448,7 @@ class FastAPI(Starlette):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             operation_id=operation_id,
             include_in_schema=include_in_schema,

fastapi/openapi/utils.py

@@ -178,6 +178,23 @@ def get_openapi_path(
                         definitions[
                             "HTTPValidationError"
                         ] = validation_error_response_definition
+            if route.responses:
+                for (additional_status_code, response) in route.responses.items():
+                    assert isinstance(
+                        response, dict
+                    ), "An additional response must be a dict"
+                    field = route.response_fields.get(additional_status_code)
+                    if field:
+                        response_schema, _ = field_schema(
+                            field, model_name_map=model_name_map, ref_prefix=REF_PREFIX
+                        )
+                        response.setdefault("content", {}).setdefault(
+                            "application/json", {}
+                        )["schema"] = response_schema
+                    response.setdefault("description", "Additional Response")
+                    operation.setdefault("responses", {})[
+                        str(additional_status_code)
+                    ] = response
             status_code = str(route.status_code)
             response_schema = {"type": "string"}
             if lenient_issubclass(route.content_type, JSONResponse):
@@ -189,13 +206,14 @@ def get_openapi_path(
                     )
                 else:
                     response_schema = {}
-            content = {route.content_type.media_type: {"schema": response_schema}}
-            operation["responses"] = {
-                status_code: {
-                    "description": route.response_description,
-                    "content": content,
-                }
-            }
+            operation.setdefault("responses", {}).setdefault(status_code, {})[
+                "description"
+            ] = route.response_description
+            operation.setdefault("responses", {}).setdefault(
+                status_code, {}
+            ).setdefault("content", {}).setdefault(route.content_type.media_type, {})[
+                "schema"
+            ] = response_schema
             if all_route_params or route.body_field:
                 operation["responses"][str(HTTP_422_UNPROCESSABLE_ENTITY)] = {
                     "description": "Validation Error",

fastapi/routing.py

@@ -1,7 +1,7 @@
 import asyncio
 import inspect
 import logging
-from typing import Any, Callable, List, Optional, Type
+from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from fastapi import params
 from fastapi.dependencies.models import Dependant
@@ -110,6 +110,7 @@ class APIRoute(routing.Route):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         name: str = None,
         methods: List[str] = None,
@@ -143,6 +144,30 @@ class APIRoute(routing.Route):
         self.summary = summary
         self.description = description or self.endpoint.__doc__
         self.response_description = response_description
+        self.responses = responses or {}
+        response_fields = {}
+        for additional_status_code, response in self.responses.items():
+            assert isinstance(response, dict), "An additional response must be a dict"
+            model = response.get("model")
+            if model:
+                assert lenient_issubclass(
+                    model, BaseModel
+                ), "A response model must be a Pydantic model"
+                response_name = f"Response_{additional_status_code}_{self.name}"
+                response_field = Field(
+                    name=response_name,
+                    type_=model,
+                    class_validators=None,
+                    default=None,
+                    required=False,
+                    model_config=UnconstrainedConfig,
+                    schema=Schema(None),
+                )
+                response_fields[additional_status_code] = response_field
+        if response_fields:
+            self.response_fields: Dict[Union[int, str], Field] = response_fields
+        else:
+            self.response_fields = {}
         self.deprecated = deprecated
         if methods is None:
             methods = ["GET"]
@@ -180,6 +205,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         methods: List[str] = None,
         operation_id: str = None,
@@ -196,6 +222,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=methods,
             operation_id=operation_id,
@@ -215,6 +242,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         methods: List[str] = None,
         operation_id: str = None,
@@ -232,6 +260,7 @@ class APIRouter(routing.Router):
                 summary=summary,
                 description=description,
                 response_description=response_description,
+                responses=responses or {},
                 deprecated=deprecated,
                 methods=methods,
                 operation_id=operation_id,
@@ -244,15 +273,23 @@ class APIRouter(routing.Router):
         return decorator
 
     def include_router(
-        self, router: "APIRouter", *, prefix: str = "", tags: List[str] = None
+        self,
+        router: "APIRouter",
+        *,
+        prefix: str = "",
+        tags: List[str] = None,
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
     ) -> None:
         if prefix:
             assert prefix.startswith("/"), "A path prefix must start with '/'"
             assert not prefix.endswith(
                 "/"
             ), "A path prefix must not end with '/', as the routes will start with '/'"
+        if responses is None:
+            responses = {}
         for route in router.routes:
             if isinstance(route, APIRoute):
+                combined_responses = {**responses, **route.responses}
                 self.add_api_route(
                     prefix + route.path,
                     route.endpoint,
@@ -262,6 +299,7 @@ class APIRouter(routing.Router):
                     summary=route.summary,
                     description=route.description,
                     response_description=route.response_description,
+                    responses=combined_responses,
                     deprecated=route.deprecated,
                     methods=route.methods,
                     operation_id=route.operation_id,
@@ -292,6 +330,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -306,6 +345,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["GET"],
             operation_id=operation_id,
@@ -324,6 +364,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -338,6 +379,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["PUT"],
             operation_id=operation_id,
@@ -356,6 +398,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -370,6 +413,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["POST"],
             operation_id=operation_id,
@@ -388,6 +432,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -402,6 +447,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["DELETE"],
             operation_id=operation_id,
@@ -420,6 +466,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -434,6 +481,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["OPTIONS"],
             operation_id=operation_id,
@@ -452,6 +500,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -466,6 +515,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["HEAD"],
             operation_id=operation_id,
@@ -484,6 +534,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -498,6 +549,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["PATCH"],
             operation_id=operation_id,
@@ -516,6 +568,7 @@ class APIRouter(routing.Router):
         summary: str = None,
         description: str = None,
         response_description: str = "Successful Response",
+        responses: Dict[Union[int, str], Dict[str, Any]] = None,
         deprecated: bool = None,
         operation_id: str = None,
         include_in_schema: bool = True,
@@ -530,6 +583,7 @@ class APIRouter(routing.Router):
             summary=summary,
             description=description,
             response_description=response_description,
+            responses=responses or {},
             deprecated=deprecated,
             methods=["TRACE"],
             operation_id=operation_id,

fastapi/utils.py

@@ -30,6 +30,8 @@ def get_flat_models_from_routes(
                 body_fields_from_routes.append(route.body_field)
             if route.response_field:
                 responses_from_routes.append(route.response_field)
+            if route.response_fields:
+                responses_from_routes.extend(route.response_fields.values())
     flat_models = get_flat_models_from_fields(
         body_fields_from_routes + responses_from_routes
     )

mkdocs.yml

@@ -44,6 +44,7 @@ nav:
         - Path Operation Configuration: 'tutorial/path-operation-configuration.md'
         - Path Operation Advanced Configuration: 'tutorial/path-operation-advanced-configuration.md'
         - Custom Response: 'tutorial/custom-response.md'
+        - Additional Responses: 'tutorial/additional-responses.md'
         - Dependencies:
             - First Steps: 'tutorial/dependencies/first-steps.md'
             - Classes as Dependencies: 'tutorial/dependencies/classes-as-dependencies.md'

scripts/test-cov-html.sh

@@ -3,4 +3,4 @@
 set -e
 set -x
 
-bash scripts/test.sh --cov-report=html
+bash scripts/test.sh --cov-report=html ${@}

tests/test_additional_response_extra.py

@@ -0,0 +1,52 @@
+from fastapi import APIRouter, FastAPI
+from starlette.testclient import TestClient
+
+router = APIRouter()
+
+sub_router = APIRouter()
+
+app = FastAPI()
+
+
+@sub_router.get("/")
+def read_item():
+    return {"id": "foo"}
+
+
+router.include_router(sub_router, prefix="/items")
+
+app.include_router(router)
+
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "summary": "Read Item Get",
+                "operationId": "read_item_items__get",
+            }
+        }
+    },
+}
+
+client = TestClient(app)
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_path_operation():
+    response = client.get("/items/")
+    assert response.status_code == 200
+    assert response.json() == {"id": "foo"}

tests/test_additional_responses_router.py

@@ -0,0 +1,95 @@
+from fastapi import APIRouter, FastAPI
+from starlette.testclient import TestClient
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/a", responses={501: {"description": "Error 1"}})
+async def a():
+    return "a"
+
+
+@router.get("/b", responses={502: {"description": "Error 2"}})
+async def b():
+    return "b"
+
+
+@router.get("/c", responses={501: {"description": "Error 3"}})
+async def c():
+    return "c"
+
+
+app.include_router(router)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/a": {
+            "get": {
+                "responses": {
+                    "501": {"description": "Error 1"},
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                },
+                "summary": "A Get",
+                "operationId": "a_a_get",
+            }
+        },
+        "/b": {
+            "get": {
+                "responses": {
+                    "502": {"description": "Error 2"},
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                },
+                "summary": "B Get",
+                "operationId": "b_b_get",
+            }
+        },
+        "/c": {
+            "get": {
+                "responses": {
+                    "501": {"description": "Error 3"},
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                },
+                "summary": "C Get",
+                "operationId": "c_c_get",
+            }
+        },
+    },
+}
+
+client = TestClient(app)
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_a():
+    response = client.get("/a")
+    assert response.status_code == 200
+    assert response.json() == "a"
+
+
+def test_b():
+    response = client.get("/b")
+    assert response.status_code == 200
+    assert response.json() == "b"
+
+
+def test_c():
+    response = client.get("/c")
+    assert response.status_code == 200
+    assert response.json() == "c"

tests/test_tutorial/test_additional_responses/test_tutorial001.py

@@ -0,0 +1,116 @@
+from starlette.testclient import TestClient
+
+from additional_responses.tutorial001 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "404": {
+                        "description": "Additional Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Message"}
+                            }
+                        },
+                    },
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Item"}
+                            }
+                        },
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item Get",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Item": {
+                "title": "Item",
+                "required": ["id", "value"],
+                "type": "object",
+                "properties": {
+                    "id": {"title": "Id", "type": "string"},
+                    "value": {"title": "Value", "type": "string"},
+                },
+            },
+            "Message": {
+                "title": "Message",
+                "required": ["message"],
+                "type": "object",
+                "properties": {"message": {"title": "Message", "type": "string"}},
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_path_operation():
+    response = client.get("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"id": "foo", "value": "there goes my hero"}
+
+
+def test_path_operation_not_found():
+    response = client.get("/items/bar")
+    assert response.status_code == 404
+    assert response.json() == {"message": "Item not found"}

tests/test_tutorial/test_additional_responses/test_tutorial002.py

@@ -0,0 +1,115 @@
+import os
+import shutil
+
+from starlette.testclient import TestClient
+
+from additional_responses.tutorial002 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "image/png": {},
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Item"}
+                            },
+                        },
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item Get",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    },
+                    {
+                        "required": False,
+                        "schema": {"title": "Img", "type": "boolean"},
+                        "name": "img",
+                        "in": "query",
+                    },
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Item": {
+                "title": "Item",
+                "required": ["id", "value"],
+                "type": "object",
+                "properties": {
+                    "id": {"title": "Id", "type": "string"},
+                    "value": {"title": "Value", "type": "string"},
+                },
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_path_operation():
+    response = client.get("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"id": "foo", "value": "there goes my hero"}
+
+
+def test_path_operation_img():
+    shutil.copy("./docs/img/favicon.png", "./image.png")
+    response = client.get("/items/foo?img=1")
+    assert response.status_code == 200
+    assert response.headers["Content-Type"] == "image/png"
+    assert len(response.content)
+    os.remove("./image.png")

tests/test_tutorial/test_additional_responses/test_tutorial003.py

@@ -0,0 +1,117 @@
+from starlette.testclient import TestClient
+
+from additional_responses.tutorial003 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "404": {
+                        "description": "The item was not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Message"}
+                            }
+                        },
+                    },
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Item"},
+                                "example": {"id": "bar", "value": "The bar tenders"},
+                            }
+                        },
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item Get",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Item": {
+                "title": "Item",
+                "required": ["id", "value"],
+                "type": "object",
+                "properties": {
+                    "id": {"title": "Id", "type": "string"},
+                    "value": {"title": "Value", "type": "string"},
+                },
+            },
+            "Message": {
+                "title": "Message",
+                "required": ["message"],
+                "type": "object",
+                "properties": {"message": {"title": "Message", "type": "string"}},
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_path_operation():
+    response = client.get("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"id": "foo", "value": "there goes my hero"}
+
+
+def test_path_operation_not_found():
+    response = client.get("/items/bar")
+    assert response.status_code == 404
+    assert response.json() == {"message": "Item not found"}

tests/test_tutorial/test_additional_responses/test_tutorial004.py

@@ -0,0 +1,118 @@
+import os
+import shutil
+
+from starlette.testclient import TestClient
+
+from additional_responses.tutorial004 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "404": {"description": "Item not found"},
+                    "302": {"description": "The item was moved"},
+                    "403": {"description": "Not enough privileges"},
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "image/png": {},
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Item"}
+                            },
+                        },
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item Get",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    },
+                    {
+                        "required": False,
+                        "schema": {"title": "Img", "type": "boolean"},
+                        "name": "img",
+                        "in": "query",
+                    },
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Item": {
+                "title": "Item",
+                "required": ["id", "value"],
+                "type": "object",
+                "properties": {
+                    "id": {"title": "Id", "type": "string"},
+                    "value": {"title": "Value", "type": "string"},
+                },
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_path_operation():
+    response = client.get("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"id": "foo", "value": "there goes my hero"}
+
+
+def test_path_operation_img():
+    shutil.copy("./docs/img/favicon.png", "./image.png")
+    response = client.get("/items/foo?img=1")
+    assert response.status_code == 200
+    assert response.headers["Content-Type"] == "image/png"
+    assert len(response.content)
+    os.remove("./image.png")

tests/test_tutorial/test_bigger_applications/test_main.py

@@ -69,10 +69,11 @@ openapi_schema = {
         "/items/": {
             "get": {
                 "responses": {
+                    "404": {"description": "Not found"},
                     "200": {
                         "description": "Successful Response",
                         "content": {"application/json": {"schema": {}}},
-                    }
+                    },
                 },
                 "tags": ["items"],
                 "summary": "Read Items Get",
@@ -82,6 +83,7 @@ openapi_schema = {
         "/items/{item_id}": {
             "get": {
                 "responses": {
+                    "404": {"description": "Not found"},
                     "200": {
                         "description": "Successful Response",
                         "content": {"application/json": {"schema": {}}},
@@ -108,7 +110,38 @@ openapi_schema = {
                         "in": "path",
                     }
                 ],
-            }
+            },
+            "put": {
+                "responses": {
+                    "404": {"description": "Not found"},
+                    "403": {"description": "Operation forbidden"},
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "tags": ["custom", "items"],
+                "summary": "Update Item Put",
+                "operationId": "update_item_items__item_id__put",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    }
+                ],
+            },
         },
     },
     "components": {
@@ -158,3 +191,15 @@ def test_get_path(path, expected_status, expected_response):
     response = client.get(path)
     assert response.status_code == expected_status
     assert response.json() == expected_response
+
+
+def test_put():
+    response = client.put("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": "foo", "name": "The Fighters"}
+
+
+def test_put_forbidden():
+    response = client.put("/items/bar")
+    assert response.status_code == 403
+    assert response.json() == {"detail": "You can only update the item: foo"}