:memo: Add docs for advanced path operation configs

diff --git a/docs/tutorial/path-operation-advanced-configuration.md b/docs/tutorial/path-operation-advanced-configuration.md
new file mode 100644 (file)
index 0000000..f88a640
--- /dev/null
+++ b/docs/tutorial/path-operation-advanced-configuration.md
@@ -0,0 +1,20 @@
+## OpenAPI operationId
+
+!!! danger
+    If you are not an "expert" in OpenAPI, you probably don't need this.
+
+You can set the OpenAPI `operationId` to be used in your path operation with the parameter `operation_id`.
+
+You would have to make sure that it is unique for each operation.
+
+```Python hl_lines="6"
+{!./tutorial/src/path-operation-advanced-configuration/tutorial001.py!}
+```
+
+## Exclude from OpenAPI
+
+To exclude a path operation from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`;
+
+```Python hl_lines="6"
+{!./tutorial/src/path-operation-advanced-configuration/tutorial002.py!}
+```

diff --git a/docs/tutorial/src/path-operation-advanced-configuration/tutorial001.py b/docs/tutorial/src/path-operation-advanced-configuration/tutorial001.py
new file mode 100644 (file)
index 0000000..fafa8ff
--- /dev/null
+++ b/docs/tutorial/src/path-operation-advanced-configuration/tutorial001.py
@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/items/", operation_id="some_specific_id_you_define")
+async def read_items():
+    return [{"item_id": "Foo"}]

diff --git a/docs/tutorial/src/path-operation-advanced-configuration/tutorial002.py b/docs/tutorial/src/path-operation-advanced-configuration/tutorial002.py
new file mode 100644 (file)
index 0000000..dcc358e
--- /dev/null
+++ b/docs/tutorial/src/path-operation-advanced-configuration/tutorial002.py
@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/items/", include_in_schema=False)
+async def read_items():
+    return [{"item_id": "Foo"}]

diff --git a/mkdocs.yml b/mkdocs.yml
index 9ec1dbbefeab1d7949c07a2a5ef70e4bca8324db..1f2b89311fdbc54bdbcab8a66daff72b7acb3be7 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -35,6 +35,7 @@ nav:
         - Request Files: 'tutorial/request-files.md'
         - Request Forms and Files: 'tutorial/request-forms-and-files.md'
         - Path Operation Configuration: 'tutorial/path-operation-configuration.md'
+        - Path Operation Advanced Configuration: 'tutorial/path-operation-advanced-configuration.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'