✨ Add support for OpenAPI 3.1.0 (#9770)

* ✨ Update OpenAPI models for JSON Schema 2020-12 and OpenAPI 3.1.0

* ✨ Add support for summary and webhooks

* ✨ Update JSON Schema for UploadFiles

* ⏪️ Revert making paths optional, to ensure always correctness

* ⏪️ Keep UploadFile as format: binary for compatibility with the rest of Pydantic bytes fields in v1

* ✨ Update version of OpenAPI generated to 3.1.0

* ✨ Update the version of Swagger UI

* 📝 Update docs about extending OpenAPI

* 📝 Update docs and links to refer to OpenAPI 3.1.0

* ✨ Update logic for handling webhooks

* ♻️ Update parameter functions and classes, deprecate example and make examples the main field

* ✅ Update tests for OpenAPI 3.1.0

* 📝 Update examples for OpenAPI metadata

* ✅ Add and update tests for OpenAPI metadata

* 📝 Add source example for webhooks

* 📝 Update docs for metadata

* 📝 Update docs for Schema extra

* 📝 Add docs for webhooks

* 🔧 Add webhooks docs to MkDocs

* ✅ Update tests for extending OpenAPI

* ✅ Add tests for webhooks

* ♻️ Refactor generation of OpenAPI and JSON Schema with params

* 📝 Update source examples for field examples

* ✅ Update tests for examples

* ➕ Make sure the minimum version of typing-extensions installed has deprecated() (already a dependency of Pydantic)

* ✏️ Fix typo in Webhooks example code

* 🔥 Remove commented out code of removed nullable field

* 🗑️ Add deprecation warnings for example argument

* ✅ Update tests to check for deprecation warnings

* ✅ Add test for webhooks with security schemes, for coverage

* 🍱 Update image for metadata, with new summary

* 🍱 Add docs image for Webhooks

* 📝 Update docs for webhooks, add docs UI image

docs_src/extending_openapi/tutorial001.py

@@ -15,7 +15,8 @@ def custom_openapi():
     openapi_schema = get_openapi(
         title="Custom title",
         version="2.5.0",
-        description="This is a very custom OpenAPI schema",
+        summary="This is a very custom OpenAPI schema",
+        description="Here's a longer description of the custom **OpenAPI** schema",
         routes=app.routes,
     )
     openapi_schema["info"]["x-logo"] = {

docs_src/metadata/tutorial001.py

@@ -18,6 +18,7 @@ You will be able to:
 app = FastAPI(
     title="ChimichangApp",
     description=description,
+    summary="Deadpool's favorite app. Nuff said.",
     version="0.0.1",
     terms_of_service="http://example.com/terms/",
     contact={

docs_src/metadata/tutorial001_1.py

@@ -0,0 +1,38 @@
+from fastapi import FastAPI
+
+description = """
+ChimichangApp API helps you do awesome stuff. 🚀
+
+## Items
+
+You can **read items**.
+
+## Users
+
+You will be able to:
+
+* **Create users** (_not implemented_).
+* **Read users** (_not implemented_).
+"""
+
+app = FastAPI(
+    title="ChimichangApp",
+    description=description,
+    summary="Deadpool's favorite app. Nuff said.",
+    version="0.0.1",
+    terms_of_service="http://example.com/terms/",
+    contact={
+        "name": "Deadpoolio the Amazing",
+        "url": "http://x-force.example.com/contact/",
+        "email": "dp@x-force.example.com",
+    },
+    license_info={
+        "name": "Apache 2.0",
+        "identifier": "MIT",
+    },
+)
+
+
+@app.get("/items/")
+async def read_items():
+    return [{"name": "Katana"}]

docs_src/openapi_webhooks/tutorial001.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Subscription(BaseModel):
+    username: str
+    montly_fee: float
+    start_date: datetime
+
+
+@app.webhooks.post("new-subscription")
+def new_subscription(body: Subscription):
+    """
+    When a new user subscribes to your service we'll send you a POST request with this
+    data to the URL that you register for the event `new-subscription` in the dashboard.
+    """
+
+
+@app.get("/users/")
+def read_users():
+    return ["Rick", "Morty"]

docs_src/schema_extra_example/tutorial001.py

@@ -14,12 +14,14 @@ class Item(BaseModel):
 
     class Config:
         schema_extra = {
-            "example": {
-                "name": "Foo",
-                "description": "A very nice Item",
-                "price": 35.4,
-                "tax": 3.2,
-            }
+            "examples": [
+                {
+                    "name": "Foo",
+                    "description": "A very nice Item",
+                    "price": 35.4,
+                    "tax": 3.2,
+                }
+            ]
         }
 
 

docs_src/schema_extra_example/tutorial001_py310.py

@@ -12,12 +12,14 @@ class Item(BaseModel):
 
     class Config:
         schema_extra = {
-            "example": {
-                "name": "Foo",
-                "description": "A very nice Item",
-                "price": 35.4,
-                "tax": 3.2,
-            }
+            "examples": [
+                {
+                    "name": "Foo",
+                    "description": "A very nice Item",
+                    "price": 35.4,
+                    "tax": 3.2,
+                }
+            ]
         }
 
 

docs_src/schema_extra_example/tutorial002.py

@@ -7,10 +7,10 @@ app = FastAPI()
 
 
 class Item(BaseModel):
-    name: str = Field(example="Foo")
-    description: Union[str, None] = Field(default=None, example="A very nice Item")
-    price: float = Field(example=35.4)
-    tax: Union[float, None] = Field(default=None, example=3.2)
+    name: str = Field(examples=["Foo"])
+    description: Union[str, None] = Field(default=None, examples=["A very nice Item"])
+    price: float = Field(examples=[35.4])
+    tax: Union[float, None] = Field(default=None, examples=[3.2])
 
 
 @app.put("/items/{item_id}")

docs_src/schema_extra_example/tutorial002_py310.py

@@ -5,10 +5,10 @@ app = FastAPI()
 
 
 class Item(BaseModel):
-    name: str = Field(example="Foo")
-    description: str | None = Field(default=None, example="A very nice Item")
-    price: float = Field(example=35.4)
-    tax: float | None = Field(default=None, example=3.2)
+    name: str = Field(examples=["Foo"])
+    description: str | None = Field(default=None, examples=["A very nice Item"])
+    price: float = Field(examples=[35.4])
+    tax: float | None = Field(default=None, examples=[3.2])
 
 
 @app.put("/items/{item_id}")

docs_src/schema_extra_example/tutorial003.py

@@ -17,12 +17,14 @@ class Item(BaseModel):
 async def update_item(
     item_id: int,
     item: Item = Body(
-        example={
-            "name": "Foo",
-            "description": "A very nice Item",
-            "price": 35.4,
-            "tax": 3.2,
-        },
+        examples=[
+            {
+                "name": "Foo",
+                "description": "A very nice Item",
+                "price": 35.4,
+                "tax": 3.2,
+            }
+        ],
     ),
 ):
     results = {"item_id": item_id, "item": item}

docs_src/schema_extra_example/tutorial003_an.py

@@ -20,12 +20,14 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            example={
-                "name": "Foo",
-                "description": "A very nice Item",
-                "price": 35.4,
-                "tax": 3.2,
-            },
+            examples=[
+                {
+                    "name": "Foo",
+                    "description": "A very nice Item",
+                    "price": 35.4,
+                    "tax": 3.2,
+                }
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial003_an_py310.py

@@ -19,12 +19,14 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            example={
-                "name": "Foo",
-                "description": "A very nice Item",
-                "price": 35.4,
-                "tax": 3.2,
-            },
+            examples=[
+                {
+                    "name": "Foo",
+                    "description": "A very nice Item",
+                    "price": 35.4,
+                    "tax": 3.2,
+                }
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial003_an_py39.py

@@ -19,12 +19,14 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            example={
-                "name": "Foo",
-                "description": "A very nice Item",
-                "price": 35.4,
-                "tax": 3.2,
-            },
+            examples=[
+                {
+                    "name": "Foo",
+                    "description": "A very nice Item",
+                    "price": 35.4,
+                    "tax": 3.2,
+                }
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial003_py310.py

@@ -15,12 +15,14 @@ class Item(BaseModel):
 async def update_item(
     item_id: int,
     item: Item = Body(
-        example={
-            "name": "Foo",
-            "description": "A very nice Item",
-            "price": 35.4,
-            "tax": 3.2,
-        },
+        examples=[
+            {
+                "name": "Foo",
+                "description": "A very nice Item",
+                "price": 35.4,
+                "tax": 3.2,
+            }
+        ],
     ),
 ):
     results = {"item_id": item_id, "item": item}

docs_src/schema_extra_example/tutorial004.py

@@ -18,8 +18,8 @@ async def update_item(
     *,
     item_id: int,
     item: Item = Body(
-        examples={
-            "normal": {
+        examples=[
+            {
                 "summary": "A normal example",
                 "description": "A **normal** item works correctly.",
                 "value": {
@@ -29,7 +29,7 @@ async def update_item(
                     "tax": 3.2,
                 },
             },
-            "converted": {
+            {
                 "summary": "An example with converted data",
                 "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                 "value": {
@@ -37,14 +37,14 @@ async def update_item(
                     "price": "35.4",
                 },
             },
-            "invalid": {
+            {
                 "summary": "Invalid data is rejected with an error",
                 "value": {
                     "name": "Baz",
                     "price": "thirty five point four",
                 },
             },
-        },
+        ],
     ),
 ):
     results = {"item_id": item_id, "item": item}

docs_src/schema_extra_example/tutorial004_an.py

@@ -21,8 +21,8 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            examples={
-                "normal": {
+            examples=[
+                {
                     "summary": "A normal example",
                     "description": "A **normal** item works correctly.",
                     "value": {
@@ -32,7 +32,7 @@ async def update_item(
                         "tax": 3.2,
                     },
                 },
-                "converted": {
+                {
                     "summary": "An example with converted data",
                     "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                     "value": {
@@ -40,14 +40,14 @@ async def update_item(
                         "price": "35.4",
                     },
                 },
-                "invalid": {
+                {
                     "summary": "Invalid data is rejected with an error",
                     "value": {
                         "name": "Baz",
                         "price": "thirty five point four",
                     },
                 },
-            },
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial004_an_py310.py

@@ -20,8 +20,8 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            examples={
-                "normal": {
+            examples=[
+                {
                     "summary": "A normal example",
                     "description": "A **normal** item works correctly.",
                     "value": {
@@ -31,7 +31,7 @@ async def update_item(
                         "tax": 3.2,
                     },
                 },
-                "converted": {
+                {
                     "summary": "An example with converted data",
                     "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                     "value": {
@@ -39,14 +39,14 @@ async def update_item(
                         "price": "35.4",
                     },
                 },
-                "invalid": {
+                {
                     "summary": "Invalid data is rejected with an error",
                     "value": {
                         "name": "Baz",
                         "price": "thirty five point four",
                     },
                 },
-            },
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial004_an_py39.py

@@ -20,8 +20,8 @@ async def update_item(
     item: Annotated[
         Item,
         Body(
-            examples={
-                "normal": {
+            examples=[
+                {
                     "summary": "A normal example",
                     "description": "A **normal** item works correctly.",
                     "value": {
@@ -31,7 +31,7 @@ async def update_item(
                         "tax": 3.2,
                     },
                 },
-                "converted": {
+                {
                     "summary": "An example with converted data",
                     "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                     "value": {
@@ -39,14 +39,14 @@ async def update_item(
                         "price": "35.4",
                     },
                 },
-                "invalid": {
+                {
                     "summary": "Invalid data is rejected with an error",
                     "value": {
                         "name": "Baz",
                         "price": "thirty five point four",
                     },
                 },
-            },
+            ],
         ),
     ],
 ):

docs_src/schema_extra_example/tutorial004_py310.py

@@ -16,8 +16,8 @@ async def update_item(
     *,
     item_id: int,
     item: Item = Body(
-        examples={
-            "normal": {
+        examples=[
+            {
                 "summary": "A normal example",
                 "description": "A **normal** item works correctly.",
                 "value": {
@@ -27,7 +27,7 @@ async def update_item(
                     "tax": 3.2,
                 },
             },
-            "converted": {
+            {
                 "summary": "An example with converted data",
                 "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                 "value": {
@@ -35,14 +35,14 @@ async def update_item(
                     "price": "35.4",
                 },
             },
-            "invalid": {
+            {
                 "summary": "Invalid data is rejected with an error",
                 "value": {
                     "name": "Baz",
                     "price": "thirty five point four",
                 },
             },
-        },
+        ],
     ),
 ):
     results = {"item_id": item_id, "item": item}