From c118f18a8d3a5c3127de90917f17a2e476612464 Mon Sep 17 00:00:00 2001
From: Pelayo Torres <pelayo.torresalonso@telefonica.com>
Date: Tue, 18 Nov 2025 12:35:55 +0100
Subject: [PATCH] New dynamic-services page

---
 doc/helper/dynamic-services.md | 153 +++++++++++++++++++++++++++++++++
 mkdocs.yml                     |   1 +
 2 files changed, 154 insertions(+)
 create mode 100644 doc/helper/dynamic-services.md

diff --git a/doc/helper/dynamic-services.md b/doc/helper/dynamic-services.md
new file mode 100644
index 00000000..6965d876
--- /dev/null
+++ b/doc/helper/dynamic-services.md
@@ -0,0 +1,153 @@
+# Adding New Services to the Helper Server
+
+This document describes the process for adding new API services to the
+Helper server using OpenAPI specifications.
+The workflow consists of **three main steps**:
+
+1.  **Generate the service code** using an OpenAPI YAML file
+2.  **Register the service manually in `config.yaml`**
+3.  **Develop the service using the available Helper tools**
+
+Once these steps are completed, the Helper server will automatically
+expose the new API when it starts.
+
+------------------------------------------------------------------------
+
+## 1. Generating a New Service
+
+New services are generated from an **OpenAPI YAML file** using the
+`generate.sh` script.
+
+### **Usage**
+
+``` bash
+./generate.sh <openapi_yaml> <service_name>
+```
+
+### **Example**
+
+``` bash
+./generate.sh openapi_myservice.yaml myservice
+```
+
+This generates the following structure:
+
+    services/myservice/
+      ├── controllers/
+      ├── models/
+      ├── core/        (to be created by the developer)
+      └── openapi/openapi.yaml
+
+> Note:
+> The `generate.sh` script **does not modify the configuration file**.
+> You must register the new service manually in the next step.
+
+------------------------------------------------------------------------
+
+## 2. Registering the Service in `config.yaml`
+
+Each service must be added to the `package_paths` section in
+`config.yaml`.
+
+### **Example entry**
+
+``` yaml
+package_paths:
+  myservice:
+    path: /myservice
+    openapi_file: myservice/openapi/openapi.yaml
+```
+
+### **Field description**
+
+| Field         | Meaning                                                   |
+|---------------|-----------------------------------------------------------|
+| `path`        | Base URL where the API will be exposed                    |
+| `openapi_file`| Relative path from the `services/` folder to the OpenAPI file |
+
+
+Once added, the Helper server will automatically load and expose this
+API on startup.
+
+------------------------------------------------------------------------
+
+## 3. Development Tools for New Services
+
+After generating and registering your service, you can start
+implementing its logic.
+The Helper provides several utilities to help with this.
+
+------------------------------------------------------------------------
+
+### Database Access (MongoDB)
+
+To access the Mongo database configured in `config.yaml`:
+
+``` python
+from db.db import get_mongo
+
+db = get_mongo()
+```
+
+You can then interact with collections:
+
+``` python
+collection = db.get_col_by_name("my_collection")
+result = collection.find_one({})
+```
+
+------------------------------------------------------------------------
+
+### Accessing Dynamic Configuration
+
+Any dynamic or service-specific values should be added to
+`config.yaml`.
+To read them inside your service:
+
+``` python
+from config import Config
+
+config = Config().get_config()
+```
+
+`config` is a Python dictionary containing the full contents of
+`config.yaml`.
+
+------------------------------------------------------------------------
+
+## Recommended Service Structure
+
+To maintain consistency across services and follow the conventions used
+in openCAPIF:
+
+-   Controllers should only handle routing, validation, and simple
+    response formatting.
+-   The core logic should be placed inside a dedicated **`core/`**
+    folder.
+
+### **Recommended folder structure**
+
+    services/myservice/
+      ├── controllers/
+      │     └── myservice_controller.py
+      ├── core/
+      │     └── myservice_core.py
+      ├── models/
+      └── openapi/openapi.yaml
+
+### **Example controller using the core layer**
+
+``` python
+from ..core.myservice_core import process_request
+
+def handle_request(body):
+    return process_request(body)
+```
+
+This creates a clean separation of concerns and keeps your service easy
+to maintain.
+
+------------------------------------------------------------------------
+
+After completing these steps, simply restart the Helper server and
+your new API will be available automatically.
diff --git a/mkdocs.yml b/mkdocs.yml
index 49a9e828..aaf20b7a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -87,6 +87,7 @@ nav:
           - Helper:
               - Introduction: ./helper/helper.md
               - Swagger: ./helper/swagger.md
+              - Dynamic Services: ./helper/dynamic-services.md
   - Getting Started:
       - Download Repository: ./gettingstarted/download.md
       - How to Run Locally: ./gettingstarted/howtorun.md
-- 
GitLab