Merge branch 'OCF-Doc57-helper-dynamic-packages' into 'develop'

# 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.

          - 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