From 07b9810b537a1e7cdacd044aef5e9020f31462a6 Mon Sep 17 00:00:00 2001
From: "luca.gobbi" <luca.gobbi@niuma.it>
Date: Tue, 10 Dec 2024 07:55:33 +0100
Subject: [PATCH 1/2] custom endpoints docs

---
 mkdocs.yml                                    |  1 +
 mkdocs/production/network/custom-endpoints.md | 66 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 mkdocs/production/network/custom-endpoints.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 829c3fa6b..d663e5b0f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -96,6 +96,7 @@ nav:
     - Network:
       - WebSocket Endpoints: production/network/ws-endpoints.md
       - HTTP Endpoints: production/network/http-endpoints.md
+      - Custom Endpoints: production/network/custom-endpoints.md
       - Clients: production/network/clients.md
     - Auth:
         - Authentication: production/auth/authentication.md
diff --git a/mkdocs/production/network/custom-endpoints.md b/mkdocs/production/network/custom-endpoints.md
new file mode 100644
index 000000000..d5f3ec1e9
--- /dev/null
+++ b/mkdocs/production/network/custom-endpoints.md
@@ -0,0 +1,66 @@
+# Custom Endpoints
+
+The Cheshire Cat is entirely based on FastAPI and leverages FastAPI routers to instantiate its base endpoints.
+Need additional endpoints to cover your specific use case? The Cat provides a specific decorator for that.
+
+## How to Create a Custom Endpoint
+
+Inside your plugin script you can use the `@endpoint` decorator to wrap any sync or async function
+that will be used as a FastAPI path operation. Here's simple example:
+
+```python
+from cat.mad_hatter.decorators import endpoint
+
+@endpoint.get(path="/hello")
+def hello_world():
+    return {"Hello":"world"}
+```
+
+The default prefix of all custom endpoints is `/custom` so you have to consume it like this:
+
+```curl
+curl http://localhost:1865/custom/hello
+```
+
+!!! note FastAPI under the hood
+    Since there's FastAPI under the hood, you can use every FastAPI operation parameters like `path`, `tags`, `response_model`, etc.
+
+```python
+
+from cat.mad_hatter.decorators import endpoint
+from pydantic import BaseModel
+from typing import List, Optional
+
+class CustomDocument(BaseModel):
+    document_id: str
+    title: str
+    content: str
+    tags: Optional[List[str]] = []
+    created_by: Optional[str] = None
+
+@endpoint.post(path="/ingest", prefix="/custom-ingestion", tags=["Custom Ingestion"], response_model=CustomDocument)
+def custom_ingestion(document: CustomDocument, stray=Depends(HTTPAuth(AuthResource.MEMORY, AuthPermission.WRITE))):
+    
+    # some custom ingestion pipeline
+    
+    return document
+
+```
+
+## Further Examples
+
+You have three different decorators available to declare custom endpoints:
+
+ - `@endpoint.get`: To declare a GET operation;
+ - `@endpoint.post`: To declare a POST operation;
+ - `@endpoint.endpoint`: To declare any other HTTP verb operation;
+
+If you use `@endpoint.endpoint` you need to specify the allowed methods like this:
+
+```python
+from cat.mad_hatter.decorators import endpoint
+
+@endpoint.endpoint(path="/delete", methods=["DELETE"], tags=["Delete Custom"])
+def custom_delete():
+    return {"result":"custom delete endpoint"}
+```
\ No newline at end of file

From e31d39d3350c4e9aa7b08df392f8254cf731f22a Mon Sep 17 00:00:00 2001
From: "luca.gobbi" <luca.gobbi@niuma.it>
Date: Tue, 10 Dec 2024 08:52:20 +0100
Subject: [PATCH 2/2] labor limae

---
 mkdocs/production/network/custom-endpoints.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/mkdocs/production/network/custom-endpoints.md b/mkdocs/production/network/custom-endpoints.md
index d5f3ec1e9..7bbce79d4 100644
--- a/mkdocs/production/network/custom-endpoints.md
+++ b/mkdocs/production/network/custom-endpoints.md
@@ -25,6 +25,8 @@ curl http://localhost:1865/custom/hello
 !!! note FastAPI under the hood
     Since there's FastAPI under the hood, you can use every FastAPI operation parameters like `path`, `tags`, `response_model`, etc.
 
+Here's a more complex example:
+
 ```python
 
 from cat.mad_hatter.decorators import endpoint
@@ -47,7 +49,10 @@ def custom_ingestion(document: CustomDocument, stray=Depends(HTTPAuth(AuthResour
 
 ```
 
-## Further Examples
+Once you activate your plugin the Cheshire Cat will add the custom endpoints to the FastAPI routes and will clear the
+`/docs` cache to reflect the new endpoints and their OpenAPI documentation.
+
+## Available Decorators
 
 You have three different decorators available to declare custom endpoints: