:memo: Add docs for application configuration (OpenAPI)

diff --git a/docs/img/tutorial/application-configuration/image01.png b/docs/img/tutorial/application-configuration/image01.png
new file mode 100644 (file)
index 0000000..e9800d5
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 e4c4723766882d6141fc247441a6c58febde48cc..a45caf7bd6263b4841a6a1c6358474e7ae64f033 100644 (file)
--- 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 4102cfc7d98dc00169107ec1829d623b682bc409..464be5e3522bf7623a5c159e52c065bb9fae4f96 100644 (file)
--- 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 296c34272c3f5ad5f819f256980e6a82dc3c5a71..955423aae1d99b5f2d71dae5db3ad37c4b79aea5 100644 (file)
--- 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:
+
+<img src="/img/tutorial/application-configuration/image01.png">
+
+## 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!}
 ```