🔖 Release 0.10.3

* Add Gitter badge

* 📝 Add links and badges to Gitter chat

.travis.yml

@@ -1,10 +1,12 @@
+dist: xenial
+
 language: python
 
 cache: pip
 
 python:
     - "3.6"
-    - "3.7-dev"
+    - "3.7"
 
 install:
     - pip install flit

Pipfile

@@ -27,6 +27,7 @@ uvicorn = "*"
 [packages]
 starlette = "==0.11.1"
 pydantic = "==0.21.0"
+databases = {extras = ["sqlite"],version = "*"}
 
 [requires]
 python_version = "3.6"

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "676c6ae13691eef64abe6638f833cb8a330612521d3fad08718b240328b4877a"
+            "sha256": "24b3b7b88d3cbe671ddbe296e64c15f8558f0e5d5df977200119872a363aac13"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -16,6 +16,37 @@
         ]
     },
     "default": {
+        "aiocontextvars": {
+            "hashes": [
+                "sha256:1e0ff5837c8b01c36a1107acdd0baf7853ebdf6c9fc43e8e311f4be37ac2038a",
+                "sha256:6ff7aee14f549d52f0446cbb84d0deddcd3fc677bcf8fbc2ce13f5756d2064dc"
+            ],
+            "markers": "python_version < '3.7'",
+            "version": "==0.2.1"
+        },
+        "aiosqlite": {
+            "hashes": [
+                "sha256:af4fed9e778756fa0ffffc7a8b14c4d7b1a57155dc5669f18e45107313f6019e"
+            ],
+            "version": "==0.9.0"
+        },
+        "contextvars": {
+            "hashes": [
+                "sha256:2341042e1c03a271813e07dba29b6b60fa85c1005ea5ed1638a076cf50b4d625"
+            ],
+            "markers": "python_version < '3.7'",
+            "version": "==2.3"
+        },
+        "databases": {
+            "extras": [
+                "sqlite"
+            ],
+            "hashes": [
+                "sha256:4a0f15669c390a04b439972426350c0ae921ddc08c42bd54f125eb2fb86ee728"
+            ],
+            "index": "pypi",
+            "version": "==0.2.0"
+        },
         "dataclasses": {
             "hashes": [
                 "sha256:454a69d788c7fda44efd71e259be79577822f5e3f53f029a22d08004e951dc9f",
@@ -24,6 +55,22 @@
             "markers": "python_version < '3.7'",
             "version": "==0.6"
         },
+        "immutables": {
+            "hashes": [
+                "sha256:1e4f4513254ef11e0230a558ee0dcb4551b914993c330005d15338da595d3750",
+                "sha256:228e38dc7a810ba4ff88909908ac47f840e5dc6c4c0da6b25009c626a9ae771c",
+                "sha256:2ae88fbfe1d04f4e5859c924e97313edf70e72b4f19871bf329b96a67ede9ba0",
+                "sha256:2d32b61c222cba1dd11f0faff67c7fb6204ef1982454e1b5b001d4b79966ef17",
+                "sha256:35af186bfac5b62522fdf2cab11120d7b0547f405aa399b6a1e443cf5f5e318c",
+                "sha256:63023fa0cceedc62e0d1535cd4ca7a1f6df3120a6d8e5c34e89037402a6fd809",
+                "sha256:6bf5857f42a96331fd0929c357dc0b36a72f339f3b6acaf870b149c96b141f69",
+                "sha256:7bb1590024a032c7a57f79faf8c8ff5e91340662550d2980e0177f67e66e9c9c",
+                "sha256:7c090687d7e623d4eca22962635b5e1a1ee2d6f9a9aca2f3fb5a184a1ffef1f2",
+                "sha256:bc36a0a8749881eebd753f696b081bd51145e4d77291d671d2e2f622e5b65d2f",
+                "sha256:d9fc6a236018d99af6453ead945a6bb55f98d14b1801a2c229dd993edc753a00"
+            ],
+            "version": "==0.6"
+        },
         "pydantic": {
             "hashes": [
                 "sha256:93fa585402e7c8c01623ea8af6ca23363e8b4c6a020b7a2de9e99fa29d642d50",
@@ -32,6 +79,12 @@
             "index": "pypi",
             "version": "==0.21.0"
         },
+        "sqlalchemy": {
+            "hashes": [
+                "sha256:781fb7b9d194ed3fc596b8f0dd4623ff160e3e825dd8c15472376a438c19598b"
+            ],
+            "version": "==1.3.1"
+        },
         "starlette": {
             "hashes": [
                 "sha256:9d48b35d1fc7521d59ae53c421297ab3878d3c7cd4b75266d77f6c73cccb78bb"
@@ -242,11 +295,11 @@
         },
         "ipython": {
             "hashes": [
-                "sha256:06de667a9e406924f97781bda22d5d76bfb39762b678762d86a466e63f65dc39",
-                "sha256:5d3e020a6b5f29df037555e5c45ab1088d6a7cf3bd84f47e0ba501eeb0c3ec82"
+                "sha256:b038baa489c38f6d853a3cfc4c635b0cda66f2864d136fe8f40c1a6e334e2a6b",
+                "sha256:f5102c1cd67e399ec8ea66bcebe6e3968ea25a8977e53f012963e5affeb1fe38"
             ],
             "markers": "python_version >= '3.3'",
-            "version": "==7.3.0"
+            "version": "==7.4.0"
         },
         "ipython-genutils": {
             "hashes": [
@@ -264,11 +317,11 @@
         },
         "isort": {
             "hashes": [
-                "sha256:18c796c2cd35eb1a1d3f012a214a542790a1aed95e29768bdcb9f2197eccbd0b",
-                "sha256:96151fca2c6e736503981896495d344781b60d18bfda78dc11b290c6125ebdb6"
+                "sha256:08f8e3f0f0b7249e9fad7e5c41e2113aba44969798a26452ee790c06f155d4ec",
+                "sha256:4e9e9c4bd1acd66cf6c36973f29b031ec752cbfd991c69695e4e259f9a756927"
             ],
             "index": "pypi",
-            "version": "==4.3.15"
+            "version": "==4.3.16"
         },
         "jedi": {
             "hashes": [
@@ -399,11 +452,11 @@
         },
         "mkdocs-material": {
             "hashes": [
-                "sha256:762a71f82c1e291c3ff067cecd9d581557da777332fd98bc0af20fd5ab4a2dd0",
-                "sha256:b2c7174ecaa81fb1d62a5f4906f99fa0e7062ced8f9a14ec4f60b1bef9feebbf"
+                "sha256:0b394aa034b25a09a5874ae2a6ccc426fd81f5764e0991217b169e31cb0c1c0e",
+                "sha256:f5bb80a2c16d045d380edb2c5b05636af1bb709cb859bfaa9d01063a11df803f"
             ],
             "index": "pypi",
-            "version": "==4.0.2"
+            "version": "==4.1.0"
         },
         "more-itertools": {
             "hashes": [
@@ -662,7 +715,6 @@
             "hashes": [
                 "sha256:781fb7b9d194ed3fc596b8f0dd4623ff160e3e825dd8c15472376a438c19598b"
             ],
-            "index": "pypi",
             "version": "==1.3.1"
         },
         "terminado": {
@@ -688,15 +740,15 @@
         },
         "tornado": {
             "hashes": [
-                "sha256:1a58f2d603476d5e462f7c28ca1dbb5ac7e51348b27a9cac849cdec3471101f8",
-                "sha256:33f93243cd46dd398e5d2bbdd75539564d1f13f25d704cfc7541db74066d6695",
-                "sha256:34e59401afcecf0381a28228daad8ed3275bcb726810654612d5e9c001f421b7",
-                "sha256:35817031611d2c296c69e5023ea1f9b5720be803e3bb119464bb2a0405d5cd70",
-                "sha256:666b335cef5cc2759c21b7394cff881f71559aaf7cb8c4458af5bb6cb7275b47",
-                "sha256:81203efb26debaaef7158187af45bc440796de9fb1df12a75b65fae11600a255",
-                "sha256:de274c65f45f6656c375cdf1759dbf0bc52902a1e999d12a35eb13020a641a53"
+                "sha256:1174dcb84d08887b55defb2cda1986faeeea715fff189ef3dc44cce99f5fca6b",
+                "sha256:2613fab506bd2aedb3722c8c64c17f8f74f4070afed6eea17f20b2115e445aec",
+                "sha256:44b82bc1146a24e5b9853d04c142576b4e8fa7a92f2e30bc364a85d1f75c4de2",
+                "sha256:457fcbee4df737d2defc181b9073758d73f54a6cfc1f280533ff48831b39f4a8",
+                "sha256:49603e1a6e24104961497ad0c07c799aec1caac7400a6762b687e74c8206677d",
+                "sha256:8c2f40b99a8153893793559919a355d7b74649a11e59f411b0b0a1793e160bc0",
+                "sha256:e1d897889c3b5a829426b7d52828fb37b28bc181cd598624e65c8be40ee3f7fa"
             ],
-            "version": "==6.0.1"
+            "version": "==6.0.2"
         },
         "traitlets": {
             "hashes": [

README.md

@@ -14,6 +14,9 @@
 <a href="https://pypi.org/project/fastapi" target="_blank">
     <img src="https://badge.fury.io/py/fastapi.svg" alt="Package version">
 </a>
+<a href="https://gitter.im/tiangolo/fastapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" target="_blank">
+    <img src="https://badges.gitter.im/tiangolo/fastapi.svg" alt="Join the chat at https://gitter.im/tiangolo/fastapi">
+</a>
 </p>
 
 ---

docs/help-fastapi.md

@@ -24,6 +24,15 @@ There you can select "Releases only".
 
 Doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **FastAPI** with bug fixes and new features.
 
+## Join the chat
+
+<a href="https://gitter.im/tiangolo/fastapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" target="_blank">
+    <img src="https://badges.gitter.im/tiangolo/fastapi.svg" alt="Join the chat at https://gitter.im/tiangolo/fastapi">
+</a>
+
+Join the chat on Gitter: <a href="https://gitter.im/tiangolo/fastapi" target="_blank">https://gitter.im/tiangolo/fastapi</a>.
+
+There you can ask quick questions, help others, share ideas, etc.
 
 ## Connect with the author
 

docs/index.md

@@ -14,6 +14,9 @@
 <a href="https://pypi.org/project/fastapi" target="_blank">
     <img src="https://badge.fury.io/py/fastapi.svg" alt="Package version">
 </a>
+<a href="https://gitter.im/tiangolo/fastapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" target="_blank">
+    <img src="https://badges.gitter.im/tiangolo/fastapi.svg" alt="Join the chat at https://gitter.im/tiangolo/fastapi">
+</a>
 </p>
 
 ---

docs/release-notes.md

@@ -1,5 +1,32 @@
 ## Next release
 
+## 0.10.3
+
+* Add Gitter chat, badge, links, etc. <a href="https://gitter.im/tiangolo/fastapi" target="_blank">https://gitter.im/tiangolo/fastapi
+</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/117" target="_blank">#117</a>.
+
+* Add docs about <a href="https://fastapi.tiangolo.com/tutorial/extending-openapi/" target="_blank">Extending OpenAPI</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/126" target="_blank">#126</a>.
+
+* Make Travis run Ubuntu Xenial (newer version) and Python 3.7 instead of Python 3.7-dev. PR <a href="https://github.com/tiangolo/fastapi/pull/92" target="_blank">#92</a> by <a href="https://github.com/blueyed" target="_blank">@blueyed</a>.
+
+* Fix duplicated param variable creation. PR <a href="https://github.com/tiangolo/fastapi/pull/123" target="_blank">#123</a> by <a href="https://github.com/yihuang" target="_blank">@yihuang</a>.
+
+* Add note in <a href="https://fastapi.tiangolo.com/tutorial/response-model/" target="_blank">Response Model docs</a> about why using a function parameter instead of a function return type annotation. PR <a href="https://github.com/tiangolo/fastapi/pull/109" target="_blank">#109</a> by <a href="https://github.com/JHSaunders" target="_blank">@JHSaunders</a>.
+
+* Fix event docs (startup/shutdown) function name. PR <a href="https://github.com/tiangolo/fastapi/pull/105" target="_blank">#105</a> by <a href="https://github.com/stratosgear" target="_blank">@stratosgear</a>.
+
+## 0.10.2
+
+* Fix OpenAPI (JSON Schema) for declarations of Python `Union` (JSON Schema `additionalProperties`). PR <a href="https://github.com/tiangolo/fastapi/pull/121" target="_blank">#121</a>.
+
+* Update <a href="https://fastapi.tiangolo.com/tutorial/background-tasks/" target="_blank">Background Tasks</a> with a note on Celery.
+
+* Document response models using unions and lists, updated at: <a href="https://fastapi.tiangolo.com/tutorial/extra-models/" target="_blank">Extra Models</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/108" target="_blank">#108</a>.
+
+## 0.10.1
+
+* Add docs and tests for <a href="https://github.com/encode/databases" target="_blank">encode/databases</a>. New docs at: <a href="https://fastapi.tiangolo.com/tutorial/async-sql-databases/" target="_blank">Async SQL (Relational) Databases</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/107" target="_blank">#107</a>.
+
 ## 0.10.0
 
 * Add support for Background Tasks in *path operation functions* and dependencies. New documentation about <a href="https://fastapi.tiangolo.com/tutorial/background-tasks/" target="_blank">Background Tasks is here</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/103" target="_blank">#103</a>.

docs/src/async_sql_databases/tutorial001.py

@@ -0,0 +1,65 @@
+from typing import List
+
+import databases
+import sqlalchemy
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+# SQLAlchemy specific code, as with any other app
+DATABASE_URL = "sqlite:///./test.db"
+# DATABASE_URL = "postgresql://user:password@postgresserver/db"
+
+database = databases.Database(DATABASE_URL)
+
+metadata = sqlalchemy.MetaData()
+
+notes = sqlalchemy.Table(
+    "notes",
+    metadata,
+    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
+    sqlalchemy.Column("text", sqlalchemy.String),
+    sqlalchemy.Column("completed", sqlalchemy.Boolean),
+)
+
+
+engine = sqlalchemy.create_engine(
+    DATABASE_URL, connect_args={"check_same_thread": False}
+)
+metadata.create_all(engine)
+
+
+class NoteIn(BaseModel):
+    text: str
+    completed: bool
+
+
+class Note(BaseModel):
+    id: int
+    text: str
+    completed: bool
+
+
+app = FastAPI()
+
+
+@app.on_event("startup")
+async def startup():
+    await database.connect()
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    await database.disconnect()
+
+
+@app.get("/notes/", response_model=List[Note])
+async def read_notes():
+    query = notes.select()
+    return await database.fetch_all(query)
+
+
+@app.post("/notes/", response_model=Note)
+async def create_note(note: NoteIn):
+    query = notes.insert().values(text=note.text, completed=note.completed)
+    last_record_id = await database.execute(query)
+    return {**note.dict(), "id": last_record_id}

docs/src/events/tutorial002.py

@@ -4,7 +4,7 @@ app = FastAPI()
 
 
 @app.on_event("shutdown")
-def startup_event():
+def shutdown_event():
     with open("log.txt", mode="a") as log:
         log.write("Application shutdown")
 

docs/src/extending_openapi/tutorial001.py

@@ -0,0 +1,28 @@
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+app = FastAPI()
+
+
+@app.get("/items/")
+async def read_items():
+    return [{"name": "Foo"}]
+
+
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+    openapi_schema = get_openapi(
+        title="Custom title",
+        version="2.5.0",
+        description="This is a very custom OpenAPI schema",
+        routes=app.routes,
+    )
+    openapi_schema["info"]["x-logo"] = {
+        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
+    }
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+
+app.openapi = custom_openapi

docs/src/extra_models/tutorial003.py

@@ -0,0 +1,35 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class BaseItem(BaseModel):
+    description: str
+    type: str
+
+
+class CarItem(BaseItem):
+    type = "car"
+
+
+class PlaneItem(BaseItem):
+    type = "plane"
+    size: int
+
+
+items = {
+    "item1": {"description": "All my friends drive a low rider", "type": "car"},
+    "item2": {
+        "description": "Music is my aeroplane, it's my aeroplane",
+        "type": "plane",
+        "size": 5,
+    },
+}
+
+
+@app.get("/items/{item_id}", response_model=Union[PlaneItem, CarItem])
+async def read_item(item_id: str):
+    return items[item_id]

docs/src/extra_models/tutorial004.py

@@ -0,0 +1,22 @@
+from typing import List
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    description: str
+
+
+items = [
+    {"name": "Foo", "description": "There comes my hero"},
+    {"name": "Red", "description": "It's my aeroplane"},
+]
+
+
+@app.get("/items/", response_model=List[Item])
+async def read_items():
+    return items

docs/tutorial/async-sql-databases.md

@@ -0,0 +1,160 @@
+You can also use <a href="https://github.com/encode/databases" target="_blank">`encode/databases`</a> with **FastAPI** to connect to databases using `async` and `await`.
+
+It is compatible with:
+
+* PostgreSQL
+* MySQL
+* SQLite
+
+In this example, we'll use **SQLite**, because it uses a single file and Python has integrated support. So, you can copy this example and run it as is.
+
+Later, for your production application, you might want to use a database server like **PostgreSQL**.
+
+!!! tip
+    You could adopt ideas from the previous section about <a href="/tutorial/sql-databases/" target="_blank">SQLAlchemy ORM</a>, like using utility functions to perform operations in the database, independent of your **FastAPI** code.
+
+    This section doesn't apply those ideas, to be equivalent to the counterpart in <a href="https://www.starlette.io/database/" target="_blank">Starlette</a>.
+
+## Import and set up `SQLAlchemy`
+
+* Import `SQLAlchemy`.
+* Create a `metadata` object.
+* Create a table `notes` using the `metadata` object.
+
+```Python hl_lines="4 14 16 17 18 19 20 21 22"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+!!! tip
+    Notice that all this code is pure SQLAlchemy Core.
+
+    `databases` is not doing anything here yet.
+
+## Import and set up `databases`
+
+* Import `databases`.
+* Create a `DATABASE_URL`.
+* Create a `database` object.
+
+```Python hl_lines="3 9 12"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+!!! tip
+    If you where connecting to a different database (e.g. PostgreSQL), you would need to change the `DATABASE_URL`.
+
+## Create the tables
+
+In this case, we are creating the tables in the same Python file, but in production, you would probably want to create them with Alembic, integrated with migrations, etc.
+
+Here, this section would run directly, right before starting your **FastAPI** application.
+
+* Create an `engine`.
+* Create all the tables from the `metadata` object.
+
+```Python hl_lines="25 26 27 28"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+## Create models
+
+Create Pydantic models for:
+
+* Notes to be created (`NoteIn`).
+* Notes to be returned (`Note`).
+
+```Python hl_lines="31 32 33 36 37 38 39"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+By creating these Pydantic models, the input data will be validated, serialized (converted), and annotated (documented).
+
+So, you will be able to see it all in the interactive API docs.
+
+## Connect and disconnect
+
+* Create your `FastAPI` application.
+* Create event handlers to connect and disconnect from the database.
+
+```Python hl_lines="42 45 46 47 50 51 52"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+## Read notes
+
+Create the *path operation function* to read notes:
+
+```Python hl_lines="55 56 57 58"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+!!! Note
+    Notice that as we communicate with the database using `await`, the *path operation function* is declared with `async`.
+
+### Notice the `response_model=List[Note]`
+
+It uses `typing.List`.
+
+That documents (and validates, serializes, filters) the output data, as a `list` of `Note`s.
+
+## Create notes
+
+Create the *path operation function* to create notes:
+
+```Python hl_lines="61 62 63 64 65"
+{!./src/async_sql_databases/tutorial001.py!}
+```
+
+!!! Note
+    Notice that as we communicate with the database using `await`, the *path operation function* is declared with `async`.
+
+### About `{**note.dict(), "id": last_record_id}`
+
+`note` is a Pydantic `Note` object.
+
+`note.dict()` returns a `dict` with its data, something like:
+
+```Python
+{
+    "text": "Some note",
+    "completed": False,
+}
+```
+
+but it doesn't have the `id` field.
+
+So we create a new `dict`, that contains the key-value pairs from `note.dict()` with:
+
+```Python
+{**note.dict()}
+```
+
+`**note.dict()` "unpacks" the key value pairs directly, so, `{**note.dict()}` would be, more or less, a copy of `note.dict()`.
+
+And then, we extend that copy `dict`, adding another key-value pair: `"id": last_record_id`:
+
+```Python
+{**note.dict(), "id": last_record_id}
+```
+
+So, the final result returned would be something like:
+
+```Python
+{
+    "id": 1,
+    "text": "Some note",
+    "completed": False,
+}
+```
+
+## Check it
+
+You can copy this code as is, and see the docs at <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+There you can see all your API documented and interact with it:
+
+<img src="/img/tutorial/async-sql-databases/image01.png">
+
+## More info
+
+You can read more about <a href="https://github.com/encode/databases" target="_blank">`encode/databases` at its GitHub page</a>.

docs/tutorial/background-tasks.md

@@ -81,6 +81,16 @@ It's still possible to use `BackgroundTask` alone in FastAPI, but you have to cr
 
 You can see more details in <a href="https://www.starlette.io/background/" target="_blank">Starlette's official docs for Background Tasks</a>.
 
+## Caveat
+
+If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like <a href="http://www.celeryproject.org/" target="_blank">Celery</a>.
+
+They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.
+
+To see an example, check the <a href="https://fastapi.tiangolo.com/project-generation/" target="_blank">Project Generators</a>, they all include Celery already configured.
+
+But if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.
+
 ## Recap
 
 Import and use `BackgroundTasks` with parameters in *path operation functions* and dependencies to add background tasks.

docs/tutorial/extending-openapi.md

@@ -0,0 +1,90 @@
+!!! warning
+    This is a rather advanced feature. You probably can skip it.
+
+    If you are just following the tutorial - user guide, you can probably skip this section.
+
+    If you already know that you need to modify the generated OpenAPI schema, continue reading.
+
+
+There are some cases where you might need to modify the generated OpenAPI schema.
+
+In this section you will see how.
+
+## The normal process
+
+The normal (default) process, is as follows.
+
+A `FastAPI` application (instance) has an `.openapi()` method that is expected to return the OpenAPI schema.
+
+As part of the application object creation, a *path operation* for `/openapi.json` (or for whatever you set your `openapi_url`) is registered.
+
+It just returns a JSON response with the result of the application's `.openapi()` method.
+
+By default, what the method `.openapi()` does is check the property `.openapi_schema` to see if it has contents and return them.
+
+If it doesn't, it generates them using the utility function at `fastapi.openapi.utils.get_openapi`.
+
+And that function `get_openapi()` receives as parameters:
+
+* `title`: The OpenAPI title, shown in the docs.
+* `version`: The version of your API, e.g. `2.5.0`.
+* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.0.2`.
+* `description`: The description of your API.
+* `routes`: A list of routes, these are each of the registered *path operations*. They are taken from `app.routes`.
+* `openapi_prefix`: The URL prefix to be used in your OpenAPI.
+
+## Overriding the defaults
+
+Using the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need.
+
+For example, let's add <a href="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo" target="_blank">ReDoc's OpenAPI extension to include a custom logo</a>.
+
+### Normal **FastAPI**
+
+First, write all your **FastAPI** application as normally:
+
+```Python hl_lines="1 4 7 8 9"
+{!./src/extending_openapi/tutorial001.py!}
+```
+
+### Generate the OpenAPI schema
+
+Then, use the same utility function to generate the OpenAPI schema, inside a `custom_openapi()` function:
+
+```Python hl_lines="2 15 16 17 18 19 20"
+{!./src/extending_openapi/tutorial001.py!}
+```
+
+### Modify the OpenAPI schema
+
+Now you can add the ReDoc extension, adding a custom `x-logo` to the `info` "object" in the OpenAPI schema:
+
+```Python hl_lines="21 22 23"
+{!./src/extending_openapi/tutorial001.py!}
+```
+
+### Cache the OpenAPI schema
+
+You can use the property `.openapi_schema` as a "cache", to store your generated schema.
+
+That way, your application won't have to generate the schema every time a user opens your API docs.
+
+It will be generated only once, and then the same cached schema will be used for the next requests.
+
+```Python hl_lines="13 14 24 25"
+{!./src/extending_openapi/tutorial001.py!}
+```
+
+### Override the method
+
+Now you can replace the `.openapi()` method with your new function.
+
+```Python hl_lines="28"
+{!./src/extending_openapi/tutorial001.py!}
+```
+
+### Check it
+
+Once you go to <a href="http://127.0.0.1:8000/redoc" target="_blank">http://127.0.0.1:8000/redoc</a> you will see that you are using your custom logo (in this example, **FastAPI**'s logo):
+
+<img src="/img/tutorial/extending-openapi/image01.png">

docs/tutorial/extra-models.md

@@ -152,6 +152,28 @@ That way, we can declare just the differences between the models (with plaintext
 {!./src/extra_models/tutorial002.py!}
 ```
 
+## `Union` or `anyOf`
+
+You can declare a response to be the `Union` of two types, that means, that the response would be any of the two.
+
+It will be defined in OpenAPI with `anyOf`.
+
+To do that, use the standard Python type hint <a href="https://docs.python.org/3/library/typing.html#typing.Union" target="_blank">`typing.Union`</a>:
+
+```Python hl_lines="1 14 15 18 19 20 33"
+{!./src/extra_models/tutorial003.py!}
+```
+
+## List of models
+
+The same way, you can declare responses of lists of objects.
+
+For that, use the standard Python `typing.List`:
+
+```Python hl_lines="1 20"
+{!./src/extra_models/tutorial004.py!}
+```
+
 ## Recap
 
 Use multiple Pydantic models and inherit freely for each case.

docs/tutorial/response-model.md

@@ -24,6 +24,9 @@ But most importantly:
 
 * Will limit the output data to that of the model. We'll see how that's important below.
 
+!!! note "Technical Details"
+    The response model is declared in this parameter instead of as a function return type annotation, because the path function may not actually return that response model but rather return a `dict`, database object or some other model, and then use the `response_model` to perform the field limiting and serialization.
+
 ## Return the same input data
 
 Here we are declaring a `UserIn` model, it will contain a plaintext password:

fastapi/__init__.py

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

fastapi/dependencies/utils.py

@@ -100,7 +100,6 @@ def get_dependant(*, path: str, call: Callable, name: str = None) -> Dependant:
                 lenient_issubclass(param.annotation, param_supported_types)
                 or param.annotation == param.empty
             ), f"Path params must be of one of the supported types"
-            param = signature_params[param_name]
             add_param_to_fields(
                 param=param,
                 dependant=dependant,

fastapi/openapi/models.py

@@ -99,7 +99,7 @@ class SchemaBase(BaseModel):
     not_: Optional[List[Any]] = PSchema(None, alias="not")  # type: ignore
     items: Optional[Any] = None
     properties: Optional[Dict[str, Any]] = None
-    additionalProperties: Optional[Union[bool, Any]] = None
+    additionalProperties: Optional[Union[Dict[str, Any], bool]] = None
     description: Optional[str] = None
     format: Optional[str] = None
     default: Optional[Any] = None
@@ -120,7 +120,7 @@ class Schema(SchemaBase):
     not_: Optional[List[SchemaBase]] = PSchema(None, alias="not")  # type: ignore
     items: Optional[SchemaBase] = None
     properties: Optional[Dict[str, SchemaBase]] = None
-    additionalProperties: Optional[Union[bool, SchemaBase]] = None
+    additionalProperties: Optional[Union[SchemaBase, bool]] = None
 
 
 class Example(BaseModel):
@@ -220,7 +220,7 @@ class Operation(BaseModel):
     operationId: Optional[str] = None
     parameters: Optional[List[Union[Parameter, Reference]]] = None
     requestBody: Optional[Union[RequestBody, Reference]] = None
-    responses: Union[Responses, Dict[Union[str], Response]]
+    responses: Union[Responses, Dict[str, Response]]
     # Workaround OpenAPI recursive reference
     callbacks: Optional[Dict[str, Union[Dict[str, Any], Reference]]] = None
     deprecated: Optional[bool] = None

mkdocs.yml

@@ -57,6 +57,7 @@ nav:
             - 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'
+        - Async SQL (Relational) Databases: 'tutorial/async-sql-databases.md'
         - NoSQL (Distributed / Big Data) Databases: 'tutorial/nosql-databases.md'
         - Bigger Applications - Multiple Files: 'tutorial/bigger-applications.md'
         - Background Tasks: 'tutorial/background-tasks.md'
@@ -66,6 +67,7 @@ nav:
         - WebSockets: 'tutorial/websockets.md'
         - 'Events: startup - shutdown': 'tutorial/events.md'
         - Debugging: 'tutorial/debugging.md'
+        - Extending OpenAPI: 'tutorial/extending-openapi.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'
     - Project Generation - Template: 'project-generation.md'

pyproject.toml

@@ -37,7 +37,8 @@ test = [
     "isort",
     "requests",
     "email_validator",
-    "sqlalchemy"
+    "sqlalchemy",
+    "databases[sqlite]",
 ]
 doc = [
     "mkdocs",

tests/test_additional_properties.py

@@ -0,0 +1,110 @@
+from typing import Dict
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from starlette.testclient import TestClient
+
+app = FastAPI()
+
+
+class Items(BaseModel):
+    items: Dict[str, int]
+
+
+@app.post("/foo")
+def foo(items: Items):
+    return items.items
+
+
+client = TestClient(app)
+
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/foo": {
+            "post": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Foo Post",
+                "operationId": "foo_foo_post",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {"$ref": "#/components/schemas/Items"}
+                        }
+                    },
+                    "required": True,
+                },
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Items": {
+                "title": "Items",
+                "required": ["items"],
+                "type": "object",
+                "properties": {
+                    "items": {
+                        "title": "Items",
+                        "type": "object",
+                        "additionalProperties": {"type": "integer"},
+                    }
+                },
+            },
+            "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_additional_properties_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_additional_properties_post():
+    response = client.post("/foo", json={"items": {"foo": 1, "bar": 2}})
+    assert response.status_code == 200
+    assert response.json() == {"foo": 1, "bar": 2}

tests/test_tutorial/test_async_sql_databases/test_tutorial001.py

@@ -0,0 +1,131 @@
+from starlette.testclient import TestClient
+
+from async_sql_databases.tutorial001 import app
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/notes/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "title": "Response_Read_Notes",
+                                    "type": "array",
+                                    "items": {"$ref": "#/components/schemas/Note"},
+                                }
+                            }
+                        },
+                    }
+                },
+                "summary": "Read Notes Get",
+                "operationId": "read_notes_notes__get",
+            },
+            "post": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Note"}
+                            }
+                        },
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Create Note Post",
+                "operationId": "create_note_notes__post",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {"$ref": "#/components/schemas/NoteIn"}
+                        }
+                    },
+                    "required": True,
+                },
+            },
+        }
+    },
+    "components": {
+        "schemas": {
+            "NoteIn": {
+                "title": "NoteIn",
+                "required": ["text", "completed"],
+                "type": "object",
+                "properties": {
+                    "text": {"title": "Text", "type": "string"},
+                    "completed": {"title": "Completed", "type": "boolean"},
+                },
+            },
+            "Note": {
+                "title": "Note",
+                "required": ["id", "text", "completed"],
+                "type": "object",
+                "properties": {
+                    "id": {"title": "Id", "type": "integer"},
+                    "text": {"title": "Text", "type": "string"},
+                    "completed": {"title": "Completed", "type": "boolean"},
+                },
+            },
+            "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():
+    with TestClient(app) as client:
+        response = client.get("/openapi.json")
+        assert response.status_code == 200
+        assert response.json() == openapi_schema
+
+
+def test_create_read():
+    with TestClient(app) as client:
+        note = {"text": "Foo bar", "completed": False}
+        response = client.post("/notes/", json=note)
+        assert response.status_code == 200
+        data = response.json()
+        assert data["text"] == note["text"]
+        assert data["completed"] == note["completed"]
+        assert "id" in data
+        response = client.get(f"/notes/")
+        assert response.status_code == 200
+        assert data in response.json()

tests/test_tutorial/test_extending_openapi/test_tutorial001.py

@@ -0,0 +1,44 @@
+from starlette.testclient import TestClient
+
+from extending_openapi.tutorial001 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {
+        "title": "Custom title",
+        "version": "2.5.0",
+        "description": "This is a very custom OpenAPI schema",
+        "x-logo": {"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"},
+    },
+    "paths": {
+        "/items/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "summary": "Read Items Get",
+                "operationId": "read_items_items__get",
+            }
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test():
+    response = client.get("/items/")
+    assert response.status_code == 200
+    assert response.json() == [{"name": "Foo"}]

tests/test_tutorial/test_extra_models/test_tutorial003.py

@@ -0,0 +1,125 @@
+from starlette.testclient import TestClient
+
+from extra_models.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": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "title": "Response_Read_Item",
+                                    "anyOf": [
+                                        {"$ref": "#/components/schemas/PlaneItem"},
+                                        {"$ref": "#/components/schemas/CarItem"},
+                                    ],
+                                }
+                            }
+                        },
+                    },
+                    "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": {
+            "PlaneItem": {
+                "title": "PlaneItem",
+                "required": ["description", "size"],
+                "type": "object",
+                "properties": {
+                    "description": {"title": "Description", "type": "string"},
+                    "type": {"title": "Type", "type": "string", "default": "plane"},
+                    "size": {"title": "Size", "type": "integer"},
+                },
+            },
+            "CarItem": {
+                "title": "CarItem",
+                "required": ["description"],
+                "type": "object",
+                "properties": {
+                    "description": {"title": "Description", "type": "string"},
+                    "type": {"title": "Type", "type": "string", "default": "car"},
+                },
+            },
+            "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_get_car():
+    response = client.get("/items/item1")
+    assert response.status_code == 200
+    assert response.json() == {
+        "description": "All my friends drive a low rider",
+        "type": "car",
+    }
+
+
+def test_get_plane():
+    response = client.get("/items/item2")
+    assert response.status_code == 200
+    assert response.json() == {
+        "description": "Music is my aeroplane, it's my aeroplane",
+        "type": "plane",
+        "size": 5,
+    }

tests/test_tutorial/test_extra_models/test_tutorial004.py

@@ -0,0 +1,60 @@
+from starlette.testclient import TestClient
+
+from extra_models.tutorial004 import app
+
+client = TestClient(app)
+
+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": {
+                                    "title": "Response_Read_Items",
+                                    "type": "array",
+                                    "items": {"$ref": "#/components/schemas/Item"},
+                                }
+                            }
+                        },
+                    }
+                },
+                "summary": "Read Items Get",
+                "operationId": "read_items_items__get",
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Item": {
+                "title": "Item",
+                "required": ["name", "description"],
+                "type": "object",
+                "properties": {
+                    "name": {"title": "Name", "type": "string"},
+                    "description": {"title": "Description", "type": "string"},
+                },
+            }
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_get_items():
+    response = client.get("/items/")
+    assert response.status_code == 200
+    assert response.json() == [
+        {"name": "Foo", "description": "There comes my hero"},
+        {"name": "Red", "description": "It's my aeroplane"},
+    ]