From d2714d0b6423469de226f7e5b33673b59e5e9604 Mon Sep 17 00:00:00 2001
From: Arpit Singh <AS00745003@techmahindra.com>
Date: Wed, 10 Dec 2025 17:55:38 +0530
Subject: [PATCH] Fix: update documentation for CPS-2428 notification
 subscription APIs

Three APIs were added to manage CPS notifications:
- Create notification subscription
- Get notification subscription
- Delete notification subscription

Swagger examples were outdated and did not reflect the correct fields.
Updated documentation to ensure accurate examples for successful API execution.

- Added missing Javadoc in notification subscription class for better clarity.

Issue-ID: CPS-3094
Change-Id: I740b7721d8cfe4cea38a9da014b99989e3e13027
Signed-off-by: Arpit Singh <AS00745003@techmahindra.com>
---
 cps-rest/docs/openapi/components.yml               | 22 +++++++++++++------
 cps-rest/docs/openapi/cpsAdminV2.yml               |  4 ++--
 .../org/onap/cps/api/CpsNotificationService.java   | 25 ++++++++++++++++++++++
 3 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/cps-rest/docs/openapi/components.yml b/cps-rest/docs/openapi/components.yml
index 93c25842d5..b2938bc435 100644
--- a/cps-rest/docs/openapi/components.yml
+++ b/cps-rest/docs/openapi/components.yml
@@ -277,12 +277,22 @@ components:
             name: "Funny"
           target-data:
             name: "Comic"
-    NotificationSubscriptionsDataSample:
+    notificationSubscriptionRequestSample:
+      value:
+        dataspace:
+          - name: my-dataspace
+            anchors:
+              anchor:
+                - name: my-anchor
+                  xpaths:
+                    xpath:
+                      - path: /shops/bookstore
+    notificationSubscriptionResponseSample:
       value:
         cps-notification-subscriptions:dataspaces:
           dataspace:
-            - name: dataspace01
-            - name: dataspace02
+            - name: my-dataspace
+            - name: bookstore-dataspace
   parameters:
     dataspaceNameInQuery:
       name: dataspace-name
@@ -370,10 +380,10 @@ components:
         type: string
         default: /dataspaces
       examples:
-        subscription by dataspace xpath:
+        dataspace xpath:
+          value: /dataspaces
+        anchor xpath:
           value: /dataspaces/dataspace[@name='dataspace01']
-        subscription by anchor xpath:
-          value: /dataspaces/dataspace[@name='dataspace01']/anchors/anchor[@name='anchor01']
     requiredXpathInQuery:
       name: xpath
       in: query
diff --git a/cps-rest/docs/openapi/cpsAdminV2.yml b/cps-rest/docs/openapi/cpsAdminV2.yml
index af2572a1f0..7c3b4d65de 100644
--- a/cps-rest/docs/openapi/cpsAdminV2.yml
+++ b/cps-rest/docs/openapi/cpsAdminV2.yml
@@ -103,7 +103,7 @@ notificationSubscription:
         content:
           application/json:
             schema:
-              $ref: 'components.yml#/components/examples/NotificationSubscriptionsDataSample'
+              $ref: 'components.yml#/components/examples/notificationSubscriptionResponseSample'
       '400':
         $ref: 'components.yml#/components/responses/BadRequest'
       '403':
@@ -128,7 +128,7 @@ notificationSubscription:
             type: object
           examples:
             dataSample:
-              $ref: 'components.yml#/components/examples/NotificationSubscriptionsDataSample'
+              $ref: 'components.yml#/components/examples/notificationSubscriptionRequestSample'
     responses:
       '201':
         $ref: 'components.yml#/components/responses/CreatedV2'
diff --git a/cps-service/src/main/java/org/onap/cps/api/CpsNotificationService.java b/cps-service/src/main/java/org/onap/cps/api/CpsNotificationService.java
index ae437753c0..cc96a64e93 100644
--- a/cps-service/src/main/java/org/onap/cps/api/CpsNotificationService.java
+++ b/cps-service/src/main/java/org/onap/cps/api/CpsNotificationService.java
@@ -25,11 +25,36 @@ import java.util.Map;
 
 public interface CpsNotificationService {
 
+    /**
+     * Creates a notification subscription for a given xpath. The dataspacename and anchor details are provided as part
+     * of the notification subscription JSON.
+     *
+     * @param notificationSubscriptionAsJson  notification subscription in JSON format
+     * @param xpath                           the location where the notification subscription is to be created
+     */
     void createNotificationSubscription(String notificationSubscriptionAsJson, String xpath);
 
+    /**
+     * Deletes a notification subscription for a given xpath.
+     *
+     * @param xpath the location where the notification subscription is to be deleted
+     */
     void deleteNotificationSubscription(String xpath);
 
+    /**
+     * Checks if notification is enabled for a given dataspace and anchor.
+     *
+     * @param dataspaceName the dataspace name
+     * @param anchorName    the anchor name
+     * @return true if notification is enabled, false otherwise
+     */
     boolean isNotificationEnabled(String dataspaceName, String anchorName);
 
+    /**
+     * Retrieves notification subscription for a given xpath.
+     *
+     * @param xpath the location where the notification subscription is to be retrieved
+     * @return list of notification subscriptions as map
+     */
     List<Map<String, Object>> getNotificationSubscription(String xpath);
 }
-- 
2.16.6