From 25b57844bcf191cedb7d8bcf44e1436dd8e40ac1 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Mon, 18 Jul 2022 22:57:17 +0300 Subject: [PATCH 01/26] feat(docs.py): add stoplight elements as docs tool --- fastapi/openapi/docs.py | 64 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index d6af17a85..8c8e5058f 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -1,5 +1,6 @@ import json from typing import Any, Dict, Optional +from enum import Enum from fastapi.encoders import jsonable_encoder from starlette.responses import HTMLResponse @@ -185,3 +186,66 @@ def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse: """ return HTMLResponse(content=html) + +class TryItCredentialPolicyOptions(Enum): + OMIT = "omit" + include = "include" + SAME_ORIGIN = "same-origin" + +class LayoutOptions(Enum): + SIDEBAR = "sidebar" + STACKED = "stacked" + +class RouterOptions(Enum): + HISTORY = "history" + HASH = "hash" + MEMORY = "memory" + STATIC = "static" + +def get_stoplight_elements_html( + *, + openapi_url: str, + title: str, + stoplight_elements_js_url: str = "https://unpkg.com/@stoplight/elements/web-components.min.js", + stoplight_elements_css_url: str = "https://unpkg.com/@stoplight/elements/styles.min.css", + stoplight_elements_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", + api_description_document: str = None, + base_path: str = None, + hide_internal:bool = False, + hide_try_it:bool = False, + try_it_cors_proxy:str = None, + try_it_credential_policy: TryItCredentialPolicyOptions = TryItCredentialPolicyOptions.OMIT, + layout: LayoutOptions = LayoutOptions.SIDEBAR, + logo: str = None, + router: RouterOptions = RouterOptions.HISTORY +) -> HTMLResponse: + html = f""" + + + + + + {title} + + + + + + + + + + + """ + return HTMLResponse(html) From af895836ac05f10083294cde20d126711e7a83a6 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Mon, 18 Jul 2022 23:01:02 +0300 Subject: [PATCH 02/26] feat(applications.py): add stoplight elements to app settings --- fastapi/applications.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/fastapi/applications.py b/fastapi/applications.py index 7530ddb9b..02db349f1 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -26,6 +26,7 @@ from fastapi.openapi.docs import ( get_redoc_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html, + get_stoplight_elements_html, ) from fastapi.openapi.utils import get_openapi from fastapi.params import Depends @@ -58,6 +59,7 @@ class FastAPI(Starlette): default_response_class: Type[Response] = Default(JSONResponse), docs_url: Optional[str] = "/docs", redoc_url: Optional[str] = "/redoc", + stoplight_elements_url: Optional[str] = "/elements", swagger_ui_oauth2_redirect_url: Optional[str] = "/docs/oauth2-redirect", swagger_ui_init_oauth: Optional[Dict[str, Any]] = None, middleware: Optional[Sequence[Middleware]] = None, @@ -97,6 +99,7 @@ class FastAPI(Starlette): self.root_path_in_servers = root_path_in_servers self.docs_url = docs_url self.redoc_url = redoc_url + self.stoplight_elements_url = stoplight_elements_url self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url self.swagger_ui_init_oauth = swagger_ui_init_oauth self.swagger_ui_parameters = swagger_ui_parameters @@ -263,6 +266,17 @@ class FastAPI(Starlette): self.add_route(self.redoc_url, redoc_html, include_in_schema=False) + if self.openapi_url and self.stoplight_elements_url: + + async def stoplight_elements_html(req: Request) -> HTMLResponse: + root_path = req.scope.get("root_path", "").rstrip("/") + openapi_url = root_path + self.openapi_url + return get_stoplight_elements_html( + openapi_url=openapi_url, title=self.title + " - Stoplight Elements" + ) + + self.add_route(self.stoplight_elements_url, stoplight_elements_html, include_in_schema=False) + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: if self.root_path: scope["root_path"] = self.root_path From 8b1c9878bf9d1755e255a272d000bbb4e3aead39 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 18 Jul 2022 20:10:33 +0000 Subject: [PATCH 03/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/applications.py | 8 ++++++-- fastapi/openapi/docs.py | 24 ++++++++++++++---------- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/fastapi/applications.py b/fastapi/applications.py index 02db349f1..19e3215fb 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -24,9 +24,9 @@ from fastapi.logger import logger from fastapi.middleware.asyncexitstack import AsyncExitStackMiddleware from fastapi.openapi.docs import ( get_redoc_html, + get_stoplight_elements_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html, - get_stoplight_elements_html, ) from fastapi.openapi.utils import get_openapi from fastapi.params import Depends @@ -275,7 +275,11 @@ class FastAPI(Starlette): openapi_url=openapi_url, title=self.title + " - Stoplight Elements" ) - self.add_route(self.stoplight_elements_url, stoplight_elements_html, include_in_schema=False) + self.add_route( + self.stoplight_elements_url, + stoplight_elements_html, + include_in_schema=False, + ) async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: if self.root_path: diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 8c8e5058f..1ecc0651c 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -1,6 +1,6 @@ import json -from typing import Any, Dict, Optional from enum import Enum +from typing import Any, Dict, Optional from fastapi.encoders import jsonable_encoder from starlette.responses import HTMLResponse @@ -187,20 +187,24 @@ def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse: """ return HTMLResponse(content=html) + class TryItCredentialPolicyOptions(Enum): OMIT = "omit" - include = "include" + include = "include" SAME_ORIGIN = "same-origin" + class LayoutOptions(Enum): SIDEBAR = "sidebar" - STACKED = "stacked" + STACKED = "stacked" + class RouterOptions(Enum): HISTORY = "history" - HASH = "hash" - MEMORY = "memory" - STATIC = "static" + HASH = "hash" + MEMORY = "memory" + STATIC = "static" + def get_stoplight_elements_html( *, @@ -211,13 +215,13 @@ def get_stoplight_elements_html( stoplight_elements_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", api_description_document: str = None, base_path: str = None, - hide_internal:bool = False, - hide_try_it:bool = False, - try_it_cors_proxy:str = None, + hide_internal: bool = False, + hide_try_it: bool = False, + try_it_cors_proxy: str = None, try_it_credential_policy: TryItCredentialPolicyOptions = TryItCredentialPolicyOptions.OMIT, layout: LayoutOptions = LayoutOptions.SIDEBAR, logo: str = None, - router: RouterOptions = RouterOptions.HISTORY + router: RouterOptions = RouterOptions.HISTORY, ) -> HTMLResponse: html = f""" From 07929dc5db5f828ee8790c9ac55c7c1ea9e79bbb Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Mon, 18 Jul 2022 23:12:37 +0300 Subject: [PATCH 04/26] fix(docs.py): replace None with empty string on params from type str --- fastapi/openapi/docs.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 8c8e5058f..d54e0c35b 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -209,14 +209,14 @@ def get_stoplight_elements_html( stoplight_elements_js_url: str = "https://unpkg.com/@stoplight/elements/web-components.min.js", stoplight_elements_css_url: str = "https://unpkg.com/@stoplight/elements/styles.min.css", stoplight_elements_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", - api_description_document: str = None, - base_path: str = None, - hide_internal:bool = False, - hide_try_it:bool = False, - try_it_cors_proxy:str = None, + api_description_document: str = "", + base_path: str = "", + hide_internal: bool = False, + hide_try_it: bool = False, + try_it_cors_proxy: str = "", try_it_credential_policy: TryItCredentialPolicyOptions = TryItCredentialPolicyOptions.OMIT, layout: LayoutOptions = LayoutOptions.SIDEBAR, - logo: str = None, + logo: str = "", router: RouterOptions = RouterOptions.HISTORY ) -> HTMLResponse: html = f""" @@ -233,15 +233,15 @@ def get_stoplight_elements_html( From 1070fee541b50e29be1268a637e7e494d0bde14f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 18 Jul 2022 20:13:51 +0000 Subject: [PATCH 05/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/openapi/docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index ded9883dd..ad97e85af 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -221,7 +221,7 @@ def get_stoplight_elements_html( try_it_credential_policy: TryItCredentialPolicyOptions = TryItCredentialPolicyOptions.OMIT, layout: LayoutOptions = LayoutOptions.SIDEBAR, logo: str = "", - router: RouterOptions = RouterOptions.HISTORY + router: RouterOptions = RouterOptions.HISTORY, ) -> HTMLResponse: html = f""" From 80cb9b75147ee597bb87eab9bb683eec3b52cb23 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Mon, 18 Jul 2022 23:33:36 +0300 Subject: [PATCH 06/26] fix(docs.py): use enum values only --- fastapi/openapi/docs.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index ded9883dd..7f1474031 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -243,10 +243,10 @@ def get_stoplight_elements_html( {'hideInternal="true"' if hide_internal == True else ''} {'hideTryIt="true"' if hide_try_it == True else ''} {f'tryItCorsProxy="{try_it_cors_proxy}"' if try_it_cors_proxy != '' else ''} - tryItCredentialPolicy="{try_it_credential_policy}" - layout="{layout}" + tryItCredentialPolicy="{try_it_credential_policy.value}" + layout="{layout.value}" {f'logo="{logo}"' if logo != '' else ''} - router="{router}" + router="{router.value}" /> From 212efca52adcbcdde10cb601a2528718720cf38c Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Mon, 18 Jul 2022 23:33:55 +0300 Subject: [PATCH 07/26] feat(test_stoplight_elements_docs.py): add tests for the new feature --- tests/test_stoplight_elements_docs.py | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 tests/test_stoplight_elements_docs.py diff --git a/tests/test_stoplight_elements_docs.py b/tests/test_stoplight_elements_docs.py new file mode 100644 index 000000000..7348d2836 --- /dev/null +++ b/tests/test_stoplight_elements_docs.py @@ -0,0 +1,21 @@ +from fastapi import FastAPI +from fastapi.testclient import TestClient + +app = FastAPI(title="White Shuli 2") + +@app.get("/pita/shuli") +async def get_shuli_in_a_pita(): + return {"shuli": "pita"} + +client = TestClient(app) + +def test_swagger_ui(): + response = client.get("/elements") + assert response.status_code == 200, response.text + print(response.text) + assert app.title in response.text + assert "Stoplight" in response.text + +def test_response(): + response = client.get("/pita/shuli") + assert response.json() == {"shuli": "pita"} From 901639098b8e4176e194f173990ab97c45e905b4 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 18 Jul 2022 20:34:37 +0000 Subject: [PATCH 08/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tests/test_stoplight_elements_docs.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/test_stoplight_elements_docs.py b/tests/test_stoplight_elements_docs.py index 7348d2836..092aab04b 100644 --- a/tests/test_stoplight_elements_docs.py +++ b/tests/test_stoplight_elements_docs.py @@ -3,12 +3,15 @@ from fastapi.testclient import TestClient app = FastAPI(title="White Shuli 2") + @app.get("/pita/shuli") async def get_shuli_in_a_pita(): return {"shuli": "pita"} + client = TestClient(app) + def test_swagger_ui(): response = client.get("/elements") assert response.status_code == 200, response.text @@ -16,6 +19,7 @@ def test_swagger_ui(): assert app.title in response.text assert "Stoplight" in response.text + def test_response(): response = client.get("/pita/shuli") assert response.json() == {"shuli": "pita"} From 4979f907328f4370fdf8438fa8cd0969f3ad442e Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 21:20:29 +0300 Subject: [PATCH 09/26] cr fixes --- tests/test_stoplight_elements_docs.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/test_stoplight_elements_docs.py b/tests/test_stoplight_elements_docs.py index 092aab04b..5d8c63f3d 100644 --- a/tests/test_stoplight_elements_docs.py +++ b/tests/test_stoplight_elements_docs.py @@ -1,18 +1,18 @@ from fastapi import FastAPI from fastapi.testclient import TestClient -app = FastAPI(title="White Shuli 2") +app = FastAPI(title="Example App") -@app.get("/pita/shuli") +@app.get("/a/b") async def get_shuli_in_a_pita(): - return {"shuli": "pita"} + return {"a": "b"} client = TestClient(app) -def test_swagger_ui(): +def test_elements_uit(): response = client.get("/elements") assert response.status_code == 200, response.text print(response.text) @@ -21,5 +21,5 @@ def test_swagger_ui(): def test_response(): - response = client.get("/pita/shuli") - assert response.json() == {"shuli": "pita"} + response = client.get("/a/b") + assert response.json() == {"a": "b"} From 703499e940e2da821a53d32ddbcd814f71d71d31 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 21:24:23 +0300 Subject: [PATCH 10/26] fix function naming --- tests/test_stoplight_elements_docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_stoplight_elements_docs.py b/tests/test_stoplight_elements_docs.py index 5d8c63f3d..e27aec38a 100644 --- a/tests/test_stoplight_elements_docs.py +++ b/tests/test_stoplight_elements_docs.py @@ -5,7 +5,7 @@ app = FastAPI(title="Example App") @app.get("/a/b") -async def get_shuli_in_a_pita(): +async def get_a_and_b(): return {"a": "b"} From b7eb62e38291874a60d90ae499958d2bca577a96 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 22:21:59 +0300 Subject: [PATCH 11/26] feat(tutorial002.py): add elements to tutorial --- docs_src/extending_openapi/tutorial002.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs_src/extending_openapi/tutorial002.py b/docs_src/extending_openapi/tutorial002.py index 23ea368f8..f7e132636 100644 --- a/docs_src/extending_openapi/tutorial002.py +++ b/docs_src/extending_openapi/tutorial002.py @@ -2,11 +2,12 @@ from fastapi import FastAPI from fastapi.openapi.docs import ( get_redoc_html, get_swagger_ui_html, + get_stoplight_elements_html, get_swagger_ui_oauth2_redirect_html, ) from fastapi.staticfiles import StaticFiles -app = FastAPI(docs_url=None, redoc_url=None) +app = FastAPI(docs_url=None, redoc_url=None, stoplight_elements_url=None) app.mount("/static", StaticFiles(directory="static"), name="static") @@ -35,7 +36,16 @@ async def redoc_html(): redoc_js_url="/static/redoc.standalone.js", ) +@app.get("/elements", include_in_schema=False) +async def elements_html(): + return get_stoplight_elements_html( + openapi_url=app.openapi_url, + title=app.title + " - Elements", + stoplight_elements_js_url="/static/web-components.min.js", + stoplight_elements_css_url="/static/styles.min.css", + ) + @app.get("/users/{username}") async def read_user(username: str): - return {"message": f"Hello {username}"} + return {"message": f"Hello {username}"} \ No newline at end of file From d652b2cc1097d9ffffd6cb9bf9c3aef14a7f46f3 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 22:22:18 +0300 Subject: [PATCH 12/26] feat(tutorial006.py): create new tutorial for elements customization --- docs/en/docs/advanced/extending-openapi.md | 57 +++++++++++++++++++--- docs_src/extending_openapi/tutorial006.py | 43 ++++++++++++++++ 2 files changed, 93 insertions(+), 7 deletions(-) create mode 100644 docs_src/extending_openapi/tutorial006.py diff --git a/docs/en/docs/advanced/extending-openapi.md b/docs/en/docs/advanced/extending-openapi.md index 36619696b..05ed02b2b 100644 --- a/docs/en/docs/advanced/extending-openapi.md +++ b/docs/en/docs/advanced/extending-openapi.md @@ -91,7 +91,7 @@ Once you go to CDN. @@ -135,10 +135,15 @@ You can probably right-click each link and select an option similar to `Save lin * `swagger-ui-bundle.js` * `swagger-ui.css` -And **ReDoc** uses the file: +**ReDoc** uses the file: * `redoc.standalone.js` +**Stoplight Elements** uses the files: + +* `web-components.min.js` +* `styles.min.css` + After that, your file structure could look like: ``` @@ -147,6 +152,8 @@ After that, your file structure could look like: │   ├── __init__.py │   ├── main.py └── static + ├── web-components.min.js + ├── styles.min.css ├── redoc.standalone.js ├── swagger-ui-bundle.js └── swagger-ui.css @@ -157,7 +164,7 @@ After that, your file structure could look like: * Import `StaticFiles`. * "Mount" a `StaticFiles()` instance in a specific path. -```Python hl_lines="7 11" +```Python hl_lines="8 12" {!../../../docs_src/extending_openapi/tutorial002.py!} ``` @@ -191,7 +198,7 @@ The first step is to disable the automatic docs, as those use the CDN by default To disable them, set their URLs to `None` when creating your `FastAPI` app: -```Python hl_lines="9" +```Python hl_lines="10" {!../../../docs_src/extending_openapi/tutorial002.py!} ``` @@ -209,7 +216,7 @@ You can re-use FastAPI's internal functions to create the HTML pages for the doc And similarly for ReDoc... -```Python hl_lines="2-6 14-22 25-27 30-36" +```Python hl_lines="2-7 15-23 26-28 31-37 39-46" {!../../../docs_src/extending_openapi/tutorial002.py!} ``` @@ -224,13 +231,13 @@ And similarly for ReDoc... Now, to be able to test that everything works, create a *path operation*: -```Python hl_lines="39-41" +```Python hl_lines="49-51" {!../../../docs_src/extending_openapi/tutorial002.py!} ``` ### Test it -Now, you should be able to disconnect your WiFi, go to your docs at http://127.0.0.1:8000/docs, and reload the page. +Now, you should be able to disconnect your WiFi, go to your docs at http://127.0.0.1:8000/elements, and reload the page. And even without Internet, you would be able to see the docs for your API and interact with it. @@ -312,3 +319,39 @@ presets: [ These are **JavaScript** objects, not strings, so you can't pass them from Python code directly. If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI *path operation* and manually write any JavaScript you need. + +## Configuring Stoplight Elements + +You can configure some extra Stoplight Elements parameters. + +To configure them, use the `get_stoplight_elements_html` built in function parameters. + +### Custom Stoplight Elements Config + +```Python hl_lines="24-37" +{!../../../docs_src/extending_openapi/tutorial006.py!} +``` + +- `openapi_url` OpenAPI document URL, supporting `http://`, `https://`, and documents containing `$ref` to other http(s) documents. +- `title` The page title +- `stoplight_elements_js_url` URL to static JS file. + - Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"` +- `stoplight_elements_css_url` URL to static CSS file. + - Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"` +- `stoplight_elements_favicon_url` URL to an image that will be used as the page favicon. + - Default: `"https://fastapi.tiangolo.com/img/favicon.png"` +- `api_description_document` OpenAPI document, provided as YAML string, JSON string or JavaScript object. +- `base_path` Helps when using `RouterOptions.HISTORY` but docs are in a subdirectory like https://example.com/api/elements. +- `hide_internal` Pass `True` to filter out any content which has been marked as internal with `x-internal`. + - Default: `False` +- `hide_try_it` Pass `True` to hide the Try It feature.. + - Default: `False` +- `try_it_cors_proxy` Pass the URL of a CORS proxy used to send requests to the Try It feature. The provided url is prepended to the URL of an actual request. +- `try_it_credential_policy` Use to fetch the credential policy for the Try It feature + - Default: `TryItCredentialPolicyOptions.OMIT` +- `layout` There are two layouts for Elements: + - Default: `LayoutOptions.SIDEBAR` Three-column design. + - `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already. +- `logo` URL to an image that will show as a small square logo next to the title, above the table of contents. +- `router` + - Default: `RouterOptions.HISTORY` \ No newline at end of file diff --git a/docs_src/extending_openapi/tutorial006.py b/docs_src/extending_openapi/tutorial006.py new file mode 100644 index 000000000..fc11e16c8 --- /dev/null +++ b/docs_src/extending_openapi/tutorial006.py @@ -0,0 +1,43 @@ +from fastapi import FastAPI +from fastapi.openapi.docs import ( + get_stoplight_elements_html, + get_swagger_ui_oauth2_redirect_html, + TryItCredentialPolicyOptions, + LayoutOptions, + RouterOptions, +) +from fastapi.staticfiles import StaticFiles + +app = FastAPI(stoplight_elements_url=None) + +app.mount("/static", StaticFiles(directory="static"), name="static") + + +@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False) +async def swagger_ui_redirect(): + return get_swagger_ui_oauth2_redirect_html() + + +@app.get("/elements", include_in_schema=False) +async def elements_html(): + return get_stoplight_elements_html( + openapi_url=app.openapi_url, + title=app.title + " - Elements", + stoplight_elements_js_url="/static/web-components.min.js", + stoplight_elements_css_url="/static/styles.min.css", + stoplight_elements_favicon_url="https://fastapi.tiangolo.com/img/favicon.png", + api_description_document="", + base_path="", + hide_internal=False, + hide_try_it=False, + try_it_cors_proxy="", + try_it_credential_policy=TryItCredentialPolicyOptions.OMIT, + layout=LayoutOptions.SIDEBAR, + logo="", + router=RouterOptions.HISTORY, + ) + + +@app.get("/users/{username}") +async def read_user(username: str): + return {"message": f"Hello {username}"} \ No newline at end of file From c43827d6bdb4ff3ab631ffa82e67ce216d34dd56 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Aug 2022 19:22:36 +0000 Subject: [PATCH 13/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs_src/extending_openapi/tutorial002.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs_src/extending_openapi/tutorial002.py b/docs_src/extending_openapi/tutorial002.py index f7e132636..cb0fa27f5 100644 --- a/docs_src/extending_openapi/tutorial002.py +++ b/docs_src/extending_openapi/tutorial002.py @@ -1,8 +1,8 @@ from fastapi import FastAPI from fastapi.openapi.docs import ( get_redoc_html, - get_swagger_ui_html, get_stoplight_elements_html, + get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html, ) from fastapi.staticfiles import StaticFiles @@ -36,6 +36,7 @@ async def redoc_html(): redoc_js_url="/static/redoc.standalone.js", ) + @app.get("/elements", include_in_schema=False) async def elements_html(): return get_stoplight_elements_html( @@ -48,4 +49,4 @@ async def elements_html(): @app.get("/users/{username}") async def read_user(username: str): - return {"message": f"Hello {username}"} \ No newline at end of file + return {"message": f"Hello {username}"} From bbffb0e402a01a011bff9b2cf6535b522e81b470 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Aug 2022 19:23:13 +0000 Subject: [PATCH 14/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/advanced/extending-openapi.md | 2 +- docs_src/extending_openapi/tutorial006.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/docs/advanced/extending-openapi.md b/docs/en/docs/advanced/extending-openapi.md index 05ed02b2b..898a9b52c 100644 --- a/docs/en/docs/advanced/extending-openapi.md +++ b/docs/en/docs/advanced/extending-openapi.md @@ -354,4 +354,4 @@ To configure them, use the `get_stoplight_elements_html` built in function param - `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already. - `logo` URL to an image that will show as a small square logo next to the title, above the table of contents. - `router` - - Default: `RouterOptions.HISTORY` \ No newline at end of file + - Default: `RouterOptions.HISTORY` diff --git a/docs_src/extending_openapi/tutorial006.py b/docs_src/extending_openapi/tutorial006.py index fc11e16c8..da58758ae 100644 --- a/docs_src/extending_openapi/tutorial006.py +++ b/docs_src/extending_openapi/tutorial006.py @@ -1,10 +1,10 @@ from fastapi import FastAPI from fastapi.openapi.docs import ( - get_stoplight_elements_html, - get_swagger_ui_oauth2_redirect_html, - TryItCredentialPolicyOptions, LayoutOptions, RouterOptions, + TryItCredentialPolicyOptions, + get_stoplight_elements_html, + get_swagger_ui_oauth2_redirect_html, ) from fastapi.staticfiles import StaticFiles @@ -40,4 +40,4 @@ async def elements_html(): @app.get("/users/{username}") async def read_user(username: str): - return {"message": f"Hello {username}"} \ No newline at end of file + return {"message": f"Hello {username}"} From aacac6620387c5aa562b16845ee4a5558d39f899 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 22:36:44 +0300 Subject: [PATCH 15/26] fix(test_tutorial): fix tests to improve coverage --- .../test_tutorial002.py | 7 +++++++ .../test_tutorial006.py | 20 +++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 tests/test_tutorial/test_extending_openapi/test_tutorial006.py diff --git a/tests/test_tutorial/test_extending_openapi/test_tutorial002.py b/tests/test_tutorial/test_extending_openapi/test_tutorial002.py index 654db2e4c..e7fd48eec 100644 --- a/tests/test_tutorial/test_extending_openapi/test_tutorial002.py +++ b/tests/test_tutorial/test_extending_openapi/test_tutorial002.py @@ -36,6 +36,13 @@ def test_redoc_html(client: TestClient): assert "/static/redoc.standalone.js" in response.text +def test_elements_html(client: TestClient): + response = client.get("/elements") + assert response.status_code == 200, response.text + assert "/static/web-components.min.js" in response.text + assert "/static/styles.min.css" in response.text + + def test_api(client: TestClient): response = client.get("/users/john") assert response.status_code == 200, response.text diff --git a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py new file mode 100644 index 000000000..34aad3d6e --- /dev/null +++ b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py @@ -0,0 +1,20 @@ +from fastapi.testclient import TestClient + +from docs_src.extending_openapi.tutorial006 import app + +client = TestClient(app) + + +def test_swagger_ui(): + response = client.get("/elements") + assert response.status_code == 200, response.text + assert 'router="history"' in response.text + assert 'layout="sidebar"' in response.text + assert 'tryItCredentialPolicy="omit"' in response.text + + + +def test_get_users(): + response = client.get("/users/foo") + assert response.status_code == 200, response.text + assert response.json() == {"message": "Hello foo"} From 740e4a80e65b8f850b2a11fd40bdbb6da209b5c6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Aug 2022 19:37:39 +0000 Subject: [PATCH 16/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tests/test_tutorial/test_extending_openapi/test_tutorial006.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py index 34aad3d6e..3671b1543 100644 --- a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py +++ b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py @@ -11,7 +11,6 @@ def test_swagger_ui(): assert 'router="history"' in response.text assert 'layout="sidebar"' in response.text assert 'tryItCredentialPolicy="omit"' in response.text - def test_get_users(): From 9e3b0156bcb71ddbbf0e5762434edd1ea07e79b4 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 22:38:31 +0300 Subject: [PATCH 17/26] fix(test_tutorial006.py): fix line breaks --- .../test_tutorial/test_extending_openapi/test_tutorial006.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py index 3671b1543..c21406afd 100644 --- a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py +++ b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py @@ -11,9 +11,11 @@ def test_swagger_ui(): assert 'router="history"' in response.text assert 'layout="sidebar"' in response.text assert 'tryItCredentialPolicy="omit"' in response.text - + def test_get_users(): response = client.get("/users/foo") assert response.status_code == 200, response.text assert response.json() == {"message": "Hello foo"} + + From b4cd1f2893b9cc018e67050cd39fd0413886f59e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Aug 2022 19:39:19 +0000 Subject: [PATCH 18/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../test_tutorial/test_extending_openapi/test_tutorial006.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py index c21406afd..3671b1543 100644 --- a/tests/test_tutorial/test_extending_openapi/test_tutorial006.py +++ b/tests/test_tutorial/test_extending_openapi/test_tutorial006.py @@ -11,11 +11,9 @@ def test_swagger_ui(): assert 'router="history"' in response.text assert 'layout="sidebar"' in response.text assert 'tryItCredentialPolicy="omit"' in response.text - + def test_get_users(): response = client.get("/users/foo") assert response.status_code == 200, response.text assert response.json() == {"message": "Hello foo"} - - From f275e356999b4f7ed0f3ef4b6859a8b28ad43397 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 23:07:12 +0300 Subject: [PATCH 19/26] fix(tutorial006.py): fix tutorial file --- docs_src/extending_openapi/tutorial006.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs_src/extending_openapi/tutorial006.py b/docs_src/extending_openapi/tutorial006.py index da58758ae..6754a4888 100644 --- a/docs_src/extending_openapi/tutorial006.py +++ b/docs_src/extending_openapi/tutorial006.py @@ -6,12 +6,9 @@ from fastapi.openapi.docs import ( get_stoplight_elements_html, get_swagger_ui_oauth2_redirect_html, ) -from fastapi.staticfiles import StaticFiles app = FastAPI(stoplight_elements_url=None) -app.mount("/static", StaticFiles(directory="static"), name="static") - @app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False) async def swagger_ui_redirect(): @@ -23,8 +20,8 @@ async def elements_html(): return get_stoplight_elements_html( openapi_url=app.openapi_url, title=app.title + " - Elements", - stoplight_elements_js_url="/static/web-components.min.js", - stoplight_elements_css_url="/static/styles.min.css", + stoplight_elements_js_url="https://unpkg.com/@stoplight/elements/web-components.min.js", + stoplight_elements_css_url="https://unpkg.com/@stoplight/elements/styles.min.css", stoplight_elements_favicon_url="https://fastapi.tiangolo.com/img/favicon.png", api_description_document="", base_path="", From 75d33426e76d9b7390b28d8be0e7f3bfa614b3a7 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 23:10:49 +0300 Subject: [PATCH 20/26] fix(tutorial006.py): remove unused --- docs_src/extending_openapi/tutorial006.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs_src/extending_openapi/tutorial006.py b/docs_src/extending_openapi/tutorial006.py index 6754a4888..e82706f6c 100644 --- a/docs_src/extending_openapi/tutorial006.py +++ b/docs_src/extending_openapi/tutorial006.py @@ -4,17 +4,11 @@ from fastapi.openapi.docs import ( RouterOptions, TryItCredentialPolicyOptions, get_stoplight_elements_html, - get_swagger_ui_oauth2_redirect_html, ) app = FastAPI(stoplight_elements_url=None) -@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False) -async def swagger_ui_redirect(): - return get_swagger_ui_oauth2_redirect_html() - - @app.get("/elements", include_in_schema=False) async def elements_html(): return get_stoplight_elements_html( From 45f749d8277978afac2289d2d0019b6b05adbfe3 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Wed, 24 Aug 2022 23:11:43 +0300 Subject: [PATCH 21/26] fix(extending-openapi.md): fix hl lines for tutorial006 --- docs/en/docs/advanced/extending-openapi.md | 68 +++++++++++----------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/en/docs/advanced/extending-openapi.md b/docs/en/docs/advanced/extending-openapi.md index 898a9b52c..525930ab9 100644 --- a/docs/en/docs/advanced/extending-openapi.md +++ b/docs/en/docs/advanced/extending-openapi.md @@ -1,7 +1,7 @@ # Extending OpenAPI !!! warning - This is a rather advanced feature. You probably can skip it. +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. @@ -17,7 +17,7 @@ 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. +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. @@ -27,11 +27,11 @@ If it doesn't, it generates them using the utility function at `fastapi.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`. +- `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`. ## Overriding the defaults @@ -132,17 +132,17 @@ You can probably right-click each link and select an option similar to `Save lin **Swagger UI** uses the files: -* `swagger-ui-bundle.js` -* `swagger-ui.css` +- `swagger-ui-bundle.js` +- `swagger-ui.css` **ReDoc** uses the file: -* `redoc.standalone.js` +- `redoc.standalone.js` **Stoplight Elements** uses the files: -* `web-components.min.js` -* `styles.min.css` +- `web-components.min.js` +- `styles.min.css` After that, your file structure could look like: @@ -161,8 +161,8 @@ After that, your file structure could look like: ### Serve the static files -* Import `StaticFiles`. -* "Mount" a `StaticFiles()` instance in a specific path. +- Import `StaticFiles`. +- "Mount" a `StaticFiles()` instance in a specific path. ```Python hl_lines="8 12" {!../../../docs_src/extending_openapi/tutorial002.py!} @@ -204,15 +204,15 @@ To disable them, set their URLs to `None` when creating your `FastAPI` app: ### Include the custom docs -Now you can create the *path operations* for the custom docs. +Now you can create the _path operations_ for the custom docs. You can re-use FastAPI's internal functions to create the HTML pages for the docs, and pass them the needed arguments: -* `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`. -* `title`: the title of your API. -* `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default. -* `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the one that your own app is now serving. -* `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the one that your own app is now serving. +- `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`. +- `title`: the title of your API. +- `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default. +- `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the one that your own app is now serving. +- `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the one that your own app is now serving. And similarly for ReDoc... @@ -221,15 +221,15 @@ And similarly for ReDoc... ``` !!! tip - The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2. +The _path operation_ for `swagger_ui_redirect` is a helper for when you use OAuth2. If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication. Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper. -### Create a *path operation* to test it +### Create a _path operation_ to test it -Now, to be able to test that everything works, create a *path operation*: +Now, to be able to test that everything works, create a _path operation_: ```Python hl_lines="49-51" {!../../../docs_src/extending_openapi/tutorial002.py!} @@ -318,7 +318,7 @@ presets: [ These are **JavaScript** objects, not strings, so you can't pass them from Python code directly. -If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI *path operation* and manually write any JavaScript you need. +If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI _path operation_ and manually write any JavaScript you need. ## Configuring Stoplight Elements @@ -328,30 +328,30 @@ To configure them, use the `get_stoplight_elements_html` built in function param ### Custom Stoplight Elements Config -```Python hl_lines="24-37" +```Python hl_lines="15-28" {!../../../docs_src/extending_openapi/tutorial006.py!} ``` - `openapi_url` OpenAPI document URL, supporting `http://`, `https://`, and documents containing `$ref` to other http(s) documents. - `title` The page title - `stoplight_elements_js_url` URL to static JS file. - - Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"` + - Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"` - `stoplight_elements_css_url` URL to static CSS file. - - Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"` + - Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"` - `stoplight_elements_favicon_url` URL to an image that will be used as the page favicon. - - Default: `"https://fastapi.tiangolo.com/img/favicon.png"` + - Default: `"https://fastapi.tiangolo.com/img/favicon.png"` - `api_description_document` OpenAPI document, provided as YAML string, JSON string or JavaScript object. - `base_path` Helps when using `RouterOptions.HISTORY` but docs are in a subdirectory like https://example.com/api/elements. - `hide_internal` Pass `True` to filter out any content which has been marked as internal with `x-internal`. - - Default: `False` + - Default: `False` - `hide_try_it` Pass `True` to hide the Try It feature.. - - Default: `False` + - Default: `False` - `try_it_cors_proxy` Pass the URL of a CORS proxy used to send requests to the Try It feature. The provided url is prepended to the URL of an actual request. - `try_it_credential_policy` Use to fetch the credential policy for the Try It feature - - Default: `TryItCredentialPolicyOptions.OMIT` + - Default: `TryItCredentialPolicyOptions.OMIT` - `layout` There are two layouts for Elements: - - Default: `LayoutOptions.SIDEBAR` Three-column design. - - `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already. + - Default: `LayoutOptions.SIDEBAR` Three-column design. + - `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already. - `logo` URL to an image that will show as a small square logo next to the title, above the table of contents. - `router` - - Default: `RouterOptions.HISTORY` + - Default: `RouterOptions.HISTORY` From 3c4b96b2752e3c14c0474402cb3bc284b3d1b2db Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Sat, 17 Dec 2022 16:19:51 +0200 Subject: [PATCH 22/26] fix: :rotating_light: Fix True comparison --- fastapi/openapi/docs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index ddb84aa84..206818e08 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -256,8 +256,8 @@ def get_stoplight_elements_html( {f'apiDescriptionUrl="{openapi_url}"' if openapi_url != '' else ''} {f'apiDescriptionDocument="{api_description_document}"' if api_description_document != '' else ''} {f'basePath="{base_path}"' if base_path != '' else ''} - {'hideInternal="true"' if hide_internal == True else ''} - {'hideTryIt="true"' if hide_try_it == True else ''} + {'hideInternal="true"' if hide_internal is True else ''} + {'hideTryIt="true"' if hide_try_it is True else ''} {f'tryItCorsProxy="{try_it_cors_proxy}"' if try_it_cors_proxy != '' else ''} tryItCredentialPolicy="{try_it_credential_policy.value}" layout="{layout.value}" From 27e8cd8c1b062bad98c4c97c2676e335108d8154 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 9 Aug 2025 19:55:20 +0000 Subject: [PATCH 23/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/openapi/docs.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 3158c66ea..797ccc1d3 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -394,15 +394,15 @@ def get_stoplight_elements_html( From d1f7817e8b4f4d84f93e4f82c11ac8c809911483 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Sat, 9 Aug 2025 23:06:32 +0300 Subject: [PATCH 24/26] Merge branch 'master' of https://github.com/fastapi/fastapi --- fastapi/applications.py | 600 ++++++++++++++++++++-------------------- 1 file changed, 300 insertions(+), 300 deletions(-) diff --git a/fastapi/applications.py b/fastapi/applications.py index 12d7e9d9e..8a20dc59b 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -65,25 +65,6 @@ class FastAPI(Starlette): def __init__( self: AppType, *, - title: str = "FastAPI", - description: str = "", - version: str = "0.1.0", - openapi_url: Optional[str] = "/openapi.json", - openapi_tags: Optional[List[Dict[str, Any]]] = None, - servers: Optional[List[Dict[str, Union[str, Any]]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - default_response_class: Type[Response] = Default(JSONResponse), - docs_url: Optional[str] = "/docs", - redoc_url: Optional[str] = "/redoc", - stoplight_elements_url: Optional[str] = "/elements", - swagger_ui_oauth2_redirect_url: Optional[str] = "/docs/oauth2-redirect", - swagger_ui_init_oauth: Optional[Dict[str, Any]] = None, - middleware: Optional[Sequence[Middleware]] = None, - exception_handlers: Optional[ - Dict[ - Union[int, Type[Exception]], - Callable[[Request, Any], Coroutine[Any, Any, Response]], - ] debug: Annotated[ bool, Doc( @@ -95,7 +76,7 @@ class FastAPI(Starlette): [Starlette docs for Applications](https://www.starlette.io/applications/#instantiating-the-application). """ ), - ]= False, + ] = False, routes: Annotated[ Optional[List[BaseRoute]], Doc( @@ -117,7 +98,7 @@ class FastAPI(Starlette): like `app.get()`, `app.post()`, etc. """ ), - ]= None, + ] = None, title: Annotated[ str, Doc( @@ -138,7 +119,7 @@ class FastAPI(Starlette): ``` """ ), - ]= "FastAPI", + ] = "FastAPI", summary: Annotated[ Optional[str], Doc( @@ -159,7 +140,7 @@ class FastAPI(Starlette): ``` """ ), - ]= None, + ] = None, description: Annotated[ str, Doc( @@ -197,7 +178,7 @@ class FastAPI(Starlette): ``` ''' ), - ]= "", + ] = "", version: Annotated[ str, Doc( @@ -221,7 +202,7 @@ class FastAPI(Starlette): ``` """ ), - ]= "0.1.0", + ] = "0.1.0", openapi_url: Annotated[ Optional[str], Doc( @@ -244,7 +225,7 @@ class FastAPI(Starlette): ``` """ ), - ]= "/openapi.json", + ] = "/openapi.json", openapi_tags: Annotated[ Optional[List[Dict[str, Any]]], Doc( @@ -304,7 +285,7 @@ class FastAPI(Starlette): ``` """ ), - ]= None, + ] = None, servers: Annotated[ Optional[List[Dict[str, Union[str, Any]]]], Doc( @@ -341,16 +322,14 @@ class FastAPI(Starlette): app = FastAPI( servers=[ - {"url": "https://stag.example.com", - "description": "Staging environment"}, - {"url": "https://prod.example.com", - "description": "Production environment"}, + {"url": "https://stag.example.com", "description": "Staging environment"}, + {"url": "https://prod.example.com", "description": "Production environment"}, ] ) ``` """ ), - ]= None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -368,12 +347,11 @@ class FastAPI(Starlette): from .dependencies import func_dep_1, func_dep_2 - app = FastAPI(dependencies=[Depends( - func_dep_1), Depends(func_dep_2)]) + app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)]) ``` """ ), - ]= None, + ] = None, default_response_class: Annotated[ Type[Response], Doc( @@ -393,7 +371,7 @@ class FastAPI(Starlette): ``` """ ), - ]= Default(JSONResponse), + ] = Default(JSONResponse), redirect_slashes: Annotated[ bool, Doc( @@ -418,7 +396,7 @@ class FastAPI(Starlette): to `/items/`. """ ), - ]= True, + ] = True, docs_url: Annotated[ Optional[str], Doc( @@ -442,7 +420,7 @@ class FastAPI(Starlette): ``` """ ), - ]= "/docs", + ] = "/docs", redoc_url: Annotated[ Optional[str], Doc( @@ -462,12 +440,11 @@ class FastAPI(Starlette): ```python from fastapi import FastAPI - app = FastAPI(docs_url="/documentation", - redoc_url="redocumentation") + app = FastAPI(docs_url="/documentation", redoc_url="redocumentation") ``` """ ), - ]= "/redoc", + ] = "/redoc", swagger_ui_oauth2_redirect_url: Annotated[ Optional[str], Doc( @@ -480,7 +457,31 @@ class FastAPI(Starlette): with Swagger UI. """ ), - ]= "/docs/oauth2-redirect", + ] = "/docs/oauth2-redirect", + stoplight_elements_url: Annotated[ + Optional[str], + Doc( + """ + The path to the alternative automatic interactive API documentation + provided by Stoplight Elements. + + The default URL is `/elements`. You can disable it by setting it to `None`. + + If `openapi_url` is set to `None`, this will be automatically disabled. + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(docs_url="/documentation", stoplight_elements_url="elementsdocs") + ``` + """ + ), + ] = "/elements", swagger_ui_init_oauth: Annotated[ Optional[Dict[str, Any]], Doc( @@ -491,7 +492,7 @@ class FastAPI(Starlette): [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/). """ ), - ]= None, + ] = None, middleware: Annotated[ Optional[Sequence[Middleware]], Doc( @@ -505,7 +506,7 @@ class FastAPI(Starlette): [FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/). """ ), - ]= None, + ] = None, exception_handlers: Annotated[ Optional[ Dict[ @@ -524,7 +525,7 @@ class FastAPI(Starlette): [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/). """ ), - ]= None, + ] = None, on_startup: Annotated[ Optional[Sequence[Callable[[], Any]]], Doc( @@ -536,7 +537,7 @@ class FastAPI(Starlette): Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). """ ), - ]= None, + ] = None, on_shutdown: Annotated[ Optional[Sequence[Callable[[], Any]]], Doc( @@ -549,7 +550,7 @@ class FastAPI(Starlette): [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). """ ), - ]= None, + ] = None, lifespan: Annotated[ Optional[Lifespan[AppType]], Doc( @@ -561,7 +562,7 @@ class FastAPI(Starlette): [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). """ ), - ]= None, + ] = None, terms_of_service: Annotated[ Optional[str], Doc( @@ -580,7 +581,7 @@ class FastAPI(Starlette): ``` """ ), - ]= None, + ] = None, contact: Annotated[ Optional[Dict[str, Union[str, Any]]], Doc( @@ -613,7 +614,7 @@ class FastAPI(Starlette): ``` """ ), - ]= None, + ] = None, license_info: Annotated[ Optional[Dict[str, Union[str, Any]]], Doc( @@ -647,7 +648,7 @@ class FastAPI(Starlette): ``` """ ), - ]= None, + ] = None, openapi_prefix: Annotated[ str, Doc( @@ -662,7 +663,7 @@ class FastAPI(Starlette): automatic. """ ), - ]= "", + ] = "", root_path: Annotated[ str, Doc( @@ -682,7 +683,7 @@ class FastAPI(Starlette): ``` """ ), - ]= "", + ] = "", root_path_in_servers: Annotated[ bool, Doc( @@ -702,7 +703,7 @@ class FastAPI(Starlette): ``` """ ), - ]= True, + ] = True, responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -718,7 +719,7 @@ class FastAPI(Starlette): [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). """ ), - ]= None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -731,7 +732,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]= None, + ] = None, webhooks: Annotated[ Optional[routing.APIRouter], Doc( @@ -747,7 +748,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/). """ ), - ]= None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -761,7 +762,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]= None, + ] = None, include_in_schema: Annotated[ bool, Doc( @@ -775,7 +776,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]= True, + ] = True, swagger_ui_parameters: Annotated[ Optional[Dict[str, Any]], Doc( @@ -787,7 +788,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/). """ ), - ]= None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -802,7 +803,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]= Default(generate_unique_id), + ] = Default(generate_unique_id), separate_input_output_schemas: Annotated[ bool, Doc( @@ -833,7 +834,7 @@ class FastAPI(Starlette): another one for output. """ ), - ]= True, + ] = True, **extra: Annotated[ Any, Doc( @@ -857,8 +858,8 @@ class FastAPI(Starlette): self.root_path_in_servers = root_path_in_servers self.docs_url = docs_url self.redoc_url = redoc_url - self.stoplight_elements_url = stoplight_elements_url self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url + self.stoplight_elements_url = stoplight_elements_url self.swagger_ui_init_oauth = swagger_ui_init_oauth self.swagger_ui_parameters = swagger_ui_parameters self.servers = servers or [] @@ -1100,30 +1101,30 @@ class FastAPI(Starlette): path: str, endpoint: Callable[..., Any], *, - response_model: Any=Default(None), - status_code: Optional[int]=None, - tags: Optional[List[Union[str, Enum]]]=None, - dependencies: Optional[Sequence[Depends]]=None, - summary: Optional[str]=None, - description: Optional[str]=None, - response_description: str="Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]]=None, - deprecated: Optional[bool]=None, - methods: Optional[List[str]]=None, - operation_id: Optional[str]=None, - response_model_include: Optional[IncEx]=None, - response_model_exclude: Optional[IncEx]=None, - response_model_by_alias: bool=True, - response_model_exclude_unset: bool=False, - response_model_exclude_defaults: bool=False, - response_model_exclude_none: bool=False, - include_in_schema: bool=True, - response_class: Union[Type[Response], DefaultPlaceholder]=Default( + response_model: Any = Default(None), + status_code: Optional[int] = None, + tags: Optional[List[Union[str, Enum]]] = None, + dependencies: Optional[Sequence[Depends]] = None, + summary: Optional[str] = None, + description: Optional[str] = None, + response_description: str = "Successful Response", + responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, + deprecated: Optional[bool] = None, + methods: Optional[List[str]] = None, + operation_id: Optional[str] = None, + response_model_include: Optional[IncEx] = None, + response_model_exclude: Optional[IncEx] = None, + response_model_by_alias: bool = True, + response_model_exclude_unset: bool = False, + response_model_exclude_defaults: bool = False, + response_model_exclude_none: bool = False, + include_in_schema: bool = True, + response_class: Union[Type[Response], DefaultPlaceholder] = Default( JSONResponse ), - name: Optional[str]=None, - openapi_extra: Optional[Dict[str, Any]]=None, - generate_unique_id_function: Callable[[routing.APIRoute], str]=Default( + name: Optional[str] = None, + openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( generate_unique_id ), ) -> None: @@ -1158,28 +1159,28 @@ class FastAPI(Starlette): self, path: str, *, - response_model: Any=Default(None), - status_code: Optional[int]=None, - tags: Optional[List[Union[str, Enum]]]=None, - dependencies: Optional[Sequence[Depends]]=None, - summary: Optional[str]=None, - description: Optional[str]=None, - response_description: str="Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]]=None, - deprecated: Optional[bool]=None, - methods: Optional[List[str]]=None, - operation_id: Optional[str]=None, - response_model_include: Optional[IncEx]=None, - response_model_exclude: Optional[IncEx]=None, - response_model_by_alias: bool=True, - response_model_exclude_unset: bool=False, - response_model_exclude_defaults: bool=False, - response_model_exclude_none: bool=False, - include_in_schema: bool=True, - response_class: Type[Response]=Default(JSONResponse), - name: Optional[str]=None, - openapi_extra: Optional[Dict[str, Any]]=None, - generate_unique_id_function: Callable[[routing.APIRoute], str]=Default( + response_model: Any = Default(None), + status_code: Optional[int] = None, + tags: Optional[List[Union[str, Enum]]] = None, + dependencies: Optional[Sequence[Depends]] = None, + summary: Optional[str] = None, + description: Optional[str] = None, + response_description: str = "Successful Response", + responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, + deprecated: Optional[bool] = None, + methods: Optional[List[str]] = None, + operation_id: Optional[str] = None, + response_model_include: Optional[IncEx] = None, + response_model_exclude: Optional[IncEx] = None, + response_model_by_alias: bool = True, + response_model_exclude_unset: bool = False, + response_model_exclude_defaults: bool = False, + response_model_exclude_none: bool = False, + include_in_schema: bool = True, + response_class: Type[Response] = Default(JSONResponse), + name: Optional[str] = None, + openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( generate_unique_id ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: @@ -1218,9 +1219,9 @@ class FastAPI(Starlette): self, path: str, endpoint: Callable[..., Any], - name: Optional[str]=None, + name: Optional[str] = None, *, - dependencies: Optional[Sequence[Depends]]=None, + dependencies: Optional[Sequence[Depends]] = None, ) -> None: self.router.add_api_websocket_route( path, @@ -1246,7 +1247,7 @@ class FastAPI(Starlette): A name for the WebSocket. Only used internally. """ ), - ]=None, + ] = None, *, dependencies: Annotated[ Optional[Sequence[Depends]], @@ -1259,7 +1260,7 @@ class FastAPI(Starlette): [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). """ ), - ]=None, + ] = None, ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Decorate a WebSocket function. @@ -1299,7 +1300,7 @@ class FastAPI(Starlette): router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")], *, prefix: Annotated[str, Doc( - "An optional path prefix for the router.")]="", + "An optional path prefix for the router.")] = "", tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -1313,7 +1314,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -1341,7 +1342,7 @@ class FastAPI(Starlette): ``` """ ), - ]=None, + ] = None, responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -1357,7 +1358,7 @@ class FastAPI(Starlette): [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -1382,7 +1383,7 @@ class FastAPI(Starlette): ``` """ ), - ]=None, + ] = None, include_in_schema: Annotated[ bool, Doc( @@ -1408,7 +1409,7 @@ class FastAPI(Starlette): ``` """ ), - ]=True, + ] = True, default_response_class: Annotated[ Type[Response], Doc( @@ -1436,7 +1437,7 @@ class FastAPI(Starlette): ``` """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -1452,7 +1453,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -1467,7 +1468,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> None: """ Include an `APIRouter` in the same app. @@ -1546,7 +1547,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -1559,7 +1560,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -1572,7 +1573,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -1584,7 +1585,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -1597,7 +1598,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -1615,7 +1616,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -1625,7 +1626,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -1635,7 +1636,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -1645,7 +1646,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -1665,7 +1666,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -1677,7 +1678,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -1689,7 +1690,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -1701,7 +1702,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -1719,7 +1720,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -1736,7 +1737,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -1753,7 +1754,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -1766,7 +1767,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -1779,7 +1780,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -1787,7 +1788,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -1803,7 +1804,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -1815,7 +1816,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -1830,7 +1831,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP GET operation. @@ -1919,7 +1920,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -1932,7 +1933,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -1945,7 +1946,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -1957,7 +1958,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -1970,7 +1971,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -1988,7 +1989,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -1998,7 +1999,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -2008,7 +2009,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -2018,7 +2019,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -2038,7 +2039,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -2050,7 +2051,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -2062,7 +2063,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -2074,7 +2075,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -2092,7 +2093,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -2109,7 +2110,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -2126,7 +2127,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -2139,7 +2140,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -2152,7 +2153,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -2160,7 +2161,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -2176,7 +2177,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -2188,7 +2189,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -2203,7 +2204,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP PUT operation. @@ -2297,7 +2298,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -2310,7 +2311,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -2323,7 +2324,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -2335,7 +2336,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -2348,7 +2349,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -2366,7 +2367,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -2376,7 +2377,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -2386,7 +2387,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -2396,7 +2397,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -2416,7 +2417,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -2428,7 +2429,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -2440,7 +2441,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -2452,7 +2453,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -2470,7 +2471,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -2487,7 +2488,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -2504,7 +2505,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -2517,7 +2518,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -2530,7 +2531,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -2538,7 +2539,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -2554,7 +2555,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -2566,7 +2567,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -2581,7 +2582,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP POST operation. @@ -2675,7 +2676,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -2688,7 +2689,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -2701,7 +2702,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -2713,7 +2714,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -2726,7 +2727,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -2744,7 +2745,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -2754,7 +2755,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -2764,7 +2765,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -2774,7 +2775,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -2794,7 +2795,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -2806,7 +2807,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -2818,7 +2819,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -2830,7 +2831,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -2848,7 +2849,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -2865,7 +2866,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -2882,7 +2883,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -2895,7 +2896,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -2908,7 +2909,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -2916,7 +2917,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -2932,7 +2933,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -2944,7 +2945,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -2959,7 +2960,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP DELETE operation. @@ -3048,7 +3049,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -3061,7 +3062,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -3074,7 +3075,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -3086,7 +3087,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -3099,7 +3100,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -3117,7 +3118,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -3127,7 +3128,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -3137,7 +3138,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -3147,7 +3148,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -3167,7 +3168,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -3179,7 +3180,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -3191,7 +3192,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -3203,7 +3204,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -3221,7 +3222,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -3238,7 +3239,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -3255,7 +3256,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -3268,7 +3269,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -3281,7 +3282,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -3289,7 +3290,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -3305,7 +3306,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -3317,7 +3318,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -3332,7 +3333,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP OPTIONS operation. @@ -3421,7 +3422,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -3434,7 +3435,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -3447,7 +3448,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -3459,7 +3460,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -3472,7 +3473,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -3490,7 +3491,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -3500,7 +3501,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -3510,7 +3511,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -3520,7 +3521,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -3540,7 +3541,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -3552,7 +3553,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -3564,7 +3565,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -3576,7 +3577,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -3594,7 +3595,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -3611,7 +3612,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -3628,7 +3629,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -3641,7 +3642,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -3654,7 +3655,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -3662,7 +3663,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -3678,7 +3679,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -3690,7 +3691,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -3705,7 +3706,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP HEAD operation. @@ -3794,7 +3795,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -3807,7 +3808,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -3820,7 +3821,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -3832,7 +3833,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -3845,7 +3846,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -3863,7 +3864,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -3873,7 +3874,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -3883,7 +3884,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -3893,7 +3894,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -3913,7 +3914,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -3925,7 +3926,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -3937,7 +3938,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -3949,7 +3950,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -3967,7 +3968,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -3984,7 +3985,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -4001,7 +4002,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -4014,7 +4015,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -4027,7 +4028,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -4035,7 +4036,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -4051,7 +4052,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -4063,7 +4064,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -4078,7 +4079,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP PATCH operation. @@ -4172,7 +4173,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). """ ), - ]=Default(None), + ] = Default(None), status_code: Annotated[ Optional[int], Doc( @@ -4185,7 +4186,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). """ ), - ]=None, + ] = None, tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( @@ -4198,7 +4199,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). """ ), - ]=None, + ] = None, dependencies: Annotated[ Optional[Sequence[Depends]], Doc( @@ -4210,7 +4211,7 @@ class FastAPI(Starlette): [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). """ ), - ]=None, + ] = None, summary: Annotated[ Optional[str], Doc( @@ -4223,7 +4224,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, description: Annotated[ Optional[str], Doc( @@ -4241,7 +4242,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). """ ), - ]=None, + ] = None, response_description: Annotated[ str, Doc( @@ -4251,7 +4252,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]="Successful Response", + ] = "Successful Response", responses: Annotated[ Optional[Dict[Union[int, str], Dict[str, Any]]], Doc( @@ -4261,7 +4262,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, deprecated: Annotated[ Optional[bool], Doc( @@ -4271,7 +4272,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), - ]=None, + ] = None, operation_id: Annotated[ Optional[str], Doc( @@ -4291,7 +4292,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=None, + ] = None, response_model_include: Annotated[ Optional[IncEx], Doc( @@ -4303,7 +4304,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_exclude: Annotated[ Optional[IncEx], Doc( @@ -4315,7 +4316,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=None, + ] = None, response_model_by_alias: Annotated[ bool, Doc( @@ -4327,7 +4328,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). """ ), - ]=True, + ] = True, response_model_exclude_unset: Annotated[ bool, Doc( @@ -4345,7 +4346,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( @@ -4362,7 +4363,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). """ ), - ]=False, + ] = False, response_model_exclude_none: Annotated[ bool, Doc( @@ -4379,7 +4380,7 @@ class FastAPI(Starlette): [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). """ ), - ]=False, + ] = False, include_in_schema: Annotated[ bool, Doc( @@ -4392,7 +4393,7 @@ class FastAPI(Starlette): [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi). """ ), - ]=True, + ] = True, response_class: Annotated[ Type[Response], Doc( @@ -4405,7 +4406,7 @@ class FastAPI(Starlette): [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). """ ), - ]=Default(JSONResponse), + ] = Default(JSONResponse), name: Annotated[ Optional[str], Doc( @@ -4413,7 +4414,7 @@ class FastAPI(Starlette): Name for this *path operation*. Only used internally. """ ), - ]=None, + ] = None, callbacks: Annotated[ Optional[List[BaseRoute]], Doc( @@ -4429,7 +4430,7 @@ class FastAPI(Starlette): [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). """ ), - ]=None, + ] = None, openapi_extra: Annotated[ Optional[Dict[str, Any]], Doc( @@ -4441,7 +4442,7 @@ class FastAPI(Starlette): [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). """ ), - ]=None, + ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( @@ -4456,7 +4457,7 @@ class FastAPI(Starlette): [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). """ ), - ]=Default(generate_unique_id), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP TRACE operation. @@ -4500,7 +4501,7 @@ class FastAPI(Starlette): ) def websocket_route( - self, path: str, name: Union[str, None]=None + self, path: str, name: Union[str, None] = None ) -> Callable[[DecoratedCallable], DecoratedCallable]: def decorator(func: DecoratedCallable) -> DecoratedCallable: self.router.add_websocket_route(path, func, name=name) @@ -4508,7 +4509,7 @@ class FastAPI(Starlette): return decorator - @ deprecated( + @deprecated( """ on_event is deprecated, use lifespan event handlers instead. @@ -4619,8 +4620,7 @@ class FastAPI(Starlette): async def unicorn_exception_handler(request: Request, exc: UnicornException): return JSONResponse( status_code=418, - content={ - "message": f"Oops! {exc.name} did something. There goes a rainbow..."}, + content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."}, ) ``` """ From 3b19dee39dbabf9f46104531ca898d3e54367201 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 9 Aug 2025 20:06:58 +0000 Subject: [PATCH 25/26] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20f?= =?UTF-8?q?ormat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/applications.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/fastapi/applications.py b/fastapi/applications.py index 8a20dc59b..14b77057a 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -973,8 +973,7 @@ class FastAPI(Starlette): self.exception_handlers: Dict[ Any, Callable[[Request, Any], Union[Response, Awaitable[Response]]] ] = {} if exception_handlers is None else dict(exception_handlers) - self.exception_handlers.setdefault( - HTTPException, http_exception_handler) + self.exception_handlers.setdefault(HTTPException, http_exception_handler) self.exception_handlers.setdefault( RequestValidationError, request_validation_exception_handler ) @@ -1052,8 +1051,7 @@ class FastAPI(Starlette): swagger_ui_parameters=self.swagger_ui_parameters, ) - self.add_route(self.docs_url, swagger_ui_html, - include_in_schema=False) + self.add_route(self.docs_url, swagger_ui_html, include_in_schema=False) if self.swagger_ui_oauth2_redirect_url: @@ -1299,8 +1297,7 @@ class FastAPI(Starlette): self, router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")], *, - prefix: Annotated[str, Doc( - "An optional path prefix for the router.")] = "", + prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", tags: Annotated[ Optional[List[Union[str, Enum]]], Doc( From 31fe59da9ce21e1fe4d641350f7bcb9da3c43534 Mon Sep 17 00:00:00 2001 From: Shahar Ilany <31574996+ShaharIlany@users.noreply.github.com> Date: Sat, 9 Aug 2025 23:13:07 +0300 Subject: [PATCH 26/26] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20Remove=20outdated?= =?UTF-8?q?=20documentation=20on=20extending=20OpenAPI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/advanced/extending-openapi.md | 357 --------------------- 1 file changed, 357 deletions(-) delete mode 100644 docs/en/docs/advanced/extending-openapi.md diff --git a/docs/en/docs/advanced/extending-openapi.md b/docs/en/docs/advanced/extending-openapi.md deleted file mode 100644 index 525930ab9..000000000 --- a/docs/en/docs/advanced/extending-openapi.md +++ /dev/null @@ -1,357 +0,0 @@ -# Extending OpenAPI - -!!! 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`. - -## 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 ReDoc's OpenAPI extension to include a custom logo. - -### Normal **FastAPI** - -First, write all your **FastAPI** application as normally: - -```Python hl_lines="1 4 7-9" -{!../../../docs_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-20" -{!../../../docs_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-23" -{!../../../docs_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" -{!../../../docs_src/extending_openapi/tutorial001.py!} -``` - -### Override the method - -Now you can replace the `.openapi()` method with your new function. - -```Python hl_lines="28" -{!../../../docs_src/extending_openapi/tutorial001.py!} -``` - -### Check it - -Once you go to http://127.0.0.1:8000/redoc you will see that you are using your custom logo (in this example, **FastAPI**'s logo): - - - -## Self-hosting JavaScript and CSS for docs - -The API docs use **Swagger UI**, **ReDoc** and **Stoplight Elements**, and each of those need some JavaScript and CSS files. - -By default, those files are served from a CDN. - -But it's possible to customize it, you can set a specific CDN, or serve the files yourself. - -That's useful, for example, if you need your app to keep working even while offline, without open Internet access, or in a local network. - -Here you'll see how to serve those files yourself, in the same FastAPI app, and configure the docs to use them. - -### Project file structure - -Let's say your project file structure looks like this: - -``` -. -├── app -│ ├── __init__.py -│ ├── main.py -``` - -Now create a directory to store those static files. - -Your new file structure could look like this: - -``` -. -├── app -│   ├── __init__.py -│   ├── main.py -└── static/ -``` - -### Download the files - -Download the static files needed for the docs and put them on that `static/` directory. - -You can probably right-click each link and select an option similar to `Save link as...`. - -**Swagger UI** uses the files: - -- `swagger-ui-bundle.js` -- `swagger-ui.css` - -**ReDoc** uses the file: - -- `redoc.standalone.js` - -**Stoplight Elements** uses the files: - -- `web-components.min.js` -- `styles.min.css` - -After that, your file structure could look like: - -``` -. -├── app -│   ├── __init__.py -│   ├── main.py -└── static - ├── web-components.min.js - ├── styles.min.css - ├── redoc.standalone.js - ├── swagger-ui-bundle.js - └── swagger-ui.css -``` - -### Serve the static files - -- Import `StaticFiles`. -- "Mount" a `StaticFiles()` instance in a specific path. - -```Python hl_lines="8 12" -{!../../../docs_src/extending_openapi/tutorial002.py!} -``` - -### Test the static files - -Start your application and go to http://127.0.0.1:8000/static/redoc.standalone.js. - -You should see a very long JavaScript file for **ReDoc**. - -It could start with something like: - -```JavaScript -/*! - * ReDoc - OpenAPI/Swagger-generated API Reference Documentation - * ------------------------------------------------------------- - * Version: "2.0.0-rc.18" - * Repo: https://github.com/Redocly/redoc - */ -!function(e,t){"object"==typeof exports&&"object"==typeof m - -... -``` - -That confirms that you are being able to serve static files from your app, and that you placed the static files for the docs in the correct place. - -Now we can configure the app to use those static files for the docs. - -### Disable the automatic docs - -The first step is to disable the automatic docs, as those use the CDN by default. - -To disable them, set their URLs to `None` when creating your `FastAPI` app: - -```Python hl_lines="10" -{!../../../docs_src/extending_openapi/tutorial002.py!} -``` - -### Include the custom docs - -Now you can create the _path operations_ for the custom docs. - -You can re-use FastAPI's internal functions to create the HTML pages for the docs, and pass them the needed arguments: - -- `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`. -- `title`: the title of your API. -- `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default. -- `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the one that your own app is now serving. -- `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the one that your own app is now serving. - -And similarly for ReDoc... - -```Python hl_lines="2-7 15-23 26-28 31-37 39-46" -{!../../../docs_src/extending_openapi/tutorial002.py!} -``` - -!!! tip -The _path operation_ for `swagger_ui_redirect` is a helper for when you use OAuth2. - - If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication. - - Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper. - -### Create a _path operation_ to test it - -Now, to be able to test that everything works, create a _path operation_: - -```Python hl_lines="49-51" -{!../../../docs_src/extending_openapi/tutorial002.py!} -``` - -### Test it - -Now, you should be able to disconnect your WiFi, go to your docs at http://127.0.0.1:8000/elements, and reload the page. - -And even without Internet, you would be able to see the docs for your API and interact with it. - -## Configuring Swagger UI - -You can configure some extra Swagger UI parameters. - -To configure them, pass the `swagger_ui_parameters` argument when creating the `FastAPI()` app object or to the `get_swagger_ui_html()` function. - -`swagger_ui_parameters` receives a dictionary with the configurations passed to Swagger UI directly. - -FastAPI converts the configurations to **JSON** to make them compatible with JavaScript, as that's what Swagger UI needs. - -### Disable Syntax Highlighting - -For example, you could disable syntax highlighting in Swagger UI. - -Without changing the settings, syntax highlighting is enabled by default: - - - -But you can disable it by setting `syntaxHighlight` to `False`: - -```Python hl_lines="3" -{!../../../docs_src/extending_openapi/tutorial003.py!} -``` - -...and then Swagger UI won't show the syntax highlighting anymore: - - - -### Change the Theme - -The same way you could set the syntax highlighting theme with the key `"syntaxHighlight.theme"` (notice that it has a dot in the middle): - -```Python hl_lines="3" -{!../../../docs_src/extending_openapi/tutorial004.py!} -``` - -That configuration would change the syntax highlighting color theme: - - - -### Change Default Swagger UI Parameters - -FastAPI includes some default configuration parameters appropriate for most of the use cases. - -It includes these default configurations: - -```Python -{!../../../fastapi/openapi/docs.py[ln:7-13]!} -``` - -You can override any of them by setting a different value in the argument `swagger_ui_parameters`. - -For example, to disable `deepLinking` you could pass these settings to `swagger_ui_parameters`: - -```Python hl_lines="3" -{!../../../docs_src/extending_openapi/tutorial005.py!} -``` - -### Other Swagger UI Parameters - -To see all the other possible configurations you can use, read the official docs for Swagger UI parameters. - -### JavaScript-only settings - -Swagger UI also allows other configurations to be **JavaScript-only** objects (for example, JavaScript functions). - -FastAPI also includes these JavaScript-only `presets` settings: - -```JavaScript -presets: [ - SwaggerUIBundle.presets.apis, - SwaggerUIBundle.SwaggerUIStandalonePreset -] -``` - -These are **JavaScript** objects, not strings, so you can't pass them from Python code directly. - -If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI _path operation_ and manually write any JavaScript you need. - -## Configuring Stoplight Elements - -You can configure some extra Stoplight Elements parameters. - -To configure them, use the `get_stoplight_elements_html` built in function parameters. - -### Custom Stoplight Elements Config - -```Python hl_lines="15-28" -{!../../../docs_src/extending_openapi/tutorial006.py!} -``` - -- `openapi_url` OpenAPI document URL, supporting `http://`, `https://`, and documents containing `$ref` to other http(s) documents. -- `title` The page title -- `stoplight_elements_js_url` URL to static JS file. - - Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"` -- `stoplight_elements_css_url` URL to static CSS file. - - Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"` -- `stoplight_elements_favicon_url` URL to an image that will be used as the page favicon. - - Default: `"https://fastapi.tiangolo.com/img/favicon.png"` -- `api_description_document` OpenAPI document, provided as YAML string, JSON string or JavaScript object. -- `base_path` Helps when using `RouterOptions.HISTORY` but docs are in a subdirectory like https://example.com/api/elements. -- `hide_internal` Pass `True` to filter out any content which has been marked as internal with `x-internal`. - - Default: `False` -- `hide_try_it` Pass `True` to hide the Try It feature.. - - Default: `False` -- `try_it_cors_proxy` Pass the URL of a CORS proxy used to send requests to the Try It feature. The provided url is prepended to the URL of an actual request. -- `try_it_credential_policy` Use to fetch the credential policy for the Try It feature - - Default: `TryItCredentialPolicyOptions.OMIT` -- `layout` There are two layouts for Elements: - - Default: `LayoutOptions.SIDEBAR` Three-column design. - - `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already. -- `logo` URL to an image that will show as a small square logo next to the title, above the table of contents. -- `router` - - Default: `RouterOptions.HISTORY`