diff --git a/docs/img/tutorial/application-configuration/image01.png b/docs/img/tutorial/application-configuration/image01.png new file mode 100644 index 000000000..e9800d532 Binary files /dev/null and b/docs/img/tutorial/application-configuration/image01.png differ diff --git a/docs/src/application_configuration/tutorial002.py b/docs/src/application_configuration/tutorial002.py index e4c472376..a45caf7bd 100644 --- a/docs/src/application_configuration/tutorial002.py +++ b/docs/src/application_configuration/tutorial002.py @@ -1,7 +1,7 @@ from fastapi import FastAPI app = FastAPI( - title="My Super Project", version="2.5.0", openapi_url="/api/v1/openapi.json" + openapi_url="/api/v1/openapi.json" ) diff --git a/docs/src/application_configuration/tutorial003.py b/docs/src/application_configuration/tutorial003.py index 4102cfc7d..464be5e35 100644 --- a/docs/src/application_configuration/tutorial003.py +++ b/docs/src/application_configuration/tutorial003.py @@ -1,10 +1,7 @@ from fastapi import FastAPI app = FastAPI( - title="My Super Project", - version="2.5.0", - openapi_url="/api/v1/openapi.json", - docs_url="/api/v1/docs", + docs_url="/documentation", redoc_url=None, ) diff --git a/docs/tutorial/application-configuration.md b/docs/tutorial/application-configuration.md index 296c34272..955423aae 100644 --- a/docs/tutorial/application-configuration.md +++ b/docs/tutorial/application-configuration.md @@ -1,13 +1,51 @@ -Coming soon... +There are several things that you can configure in your FastAPI application. -```Python +## Title, description, and version + +You can set the: + +* Title: used as your API's title/name, in OpenAPI and the automatic API docs UIs. +* Description: the description of your API, in OpenAPI and the automatic API docs UIs. +* Version: the version of your API, e.g. `v2` or `2.5.0`. + * Useful for example if you had a previous version of the application, also using OpenAPI. + +To set them, use the parameters `title`, `description`, and `version`: + +```Python hl_lines="4 5 6" {!./src/application_configuration/tutorial001.py!} ``` -```Python +With this configuration, the automatic API docs would look like: + + + +## OpenAPI URL + +By default, the OpenAPI schema is served at `/openapi.json`. + +But you can configure it with the parameter `openapi_url`. + +For example, to set it to be served at `/api/v1/openapi.json`: + +```Python hl_lines="4" {!./src/application_configuration/tutorial002.py!} ``` -```Python +If you want to disable the OpenAPI schema completely you can set `openapi_url=None`. + +## Docs URLs + +You can configure the two documentation user interfaces included: + +* **Swagger UI**: served at `/docs`. + * You can set its URL with the parameter `docs_url`. + * You can disable it by setting `docs_url=None`. +* ReDoc: served at `/redoc`. + * You can set its URL with the parameter `redoc_url`. + * You can disable it by setting `redoc_url=None`. + +For example, to set Swagger UI to be served at `/documentation` and disable ReDoc: + +```Python hl_lines="4 5" {!./src/application_configuration/tutorial003.py!} ```