Adding NCMP Stubs documentation

Issue-ID: CPS-1858
Change-Id: I90017d9d9c6e937292e9de45c0e8228357414e16
Signed-off-by: waqas.ikram <waqas.ikram@est.tech>

5 files changed, 247 insertions, 18 deletions

diff --git a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/pom.xml b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/pom.xml
index 83699b9349..d2cce87977 100644
--- a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/pom.xml
+++ b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/pom.xml
@@ -46,11 +46,42 @@
             <groupId>org.onap.cps</groupId>
             <artifactId>cps-ncmp-rest</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-server</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.servlet</groupId>
+            <artifactId>jakarta.servlet-api</artifactId>
+        </dependency>
         <!-- T E S T - D E P E N D E N C I E S -->
         <dependency>
             <groupId>org.spockframework</groupId>
             <artifactId>spock-core</artifactId>
             <scope>test</scope>
         </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.junit.vintage</groupId>
+                    <artifactId>junit-vintage-engine</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.spockframework</groupId>
+            <artifactId>spock-spring</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.spockframework</groupId>
+            <artifactId>spock-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
+    
 </project>
\ No newline at end of file
diff --git a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/java/org/onap/cps/ncmp/rest/stub/controller/NetworkCmProxyStubController.java b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/java/org/onap/cps/ncmp/rest/stub/controller/NetworkCmProxyStubController.java
index 198b14fc35..e33af45f9b 100644
--- a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/java/org/onap/cps/ncmp/rest/stub/controller/NetworkCmProxyStubController.java
+++ b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/java/org/onap/cps/ncmp/rest/stub/controller/NetworkCmProxyStubController.java
@@ -141,13 +141,13 @@ public class NetworkCmProxyStubController implements NetworkCmProxyApi {
     }
 
     @Override
-    public ResponseEntity<Void> createResourceDataRunningForCmHandle(@NotNull @Valid final String resourceIdentifier,
-                                                                     final String datastoreName, final String cmHandle,
-                                                                     @Valid final Object body,
+    public ResponseEntity<Void> createResourceDataRunningForCmHandle(final String datastoreName, final String cmHandle,
+                                                                     @NotNull @Valid final String resourceIdentifier, 
+                                                                     @Valid final Object body, 
                                                                      final String contentType) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
     }
-
+    
     @Override
     public ResponseEntity<Void> deleteResourceDataRunningForCmHandle(final String datastoreName, final String cmHandle,
                                                                      @NotNull @Valid final String resourceIdentifier,
@@ -183,13 +183,13 @@ public class NetworkCmProxyStubController implements NetworkCmProxyApi {
     }
 
     @Override
-    public ResponseEntity<Object> patchResourceDataRunningForCmHandle(@NotNull @Valid final String resourceIdentifier,
-                                                                      final String datastoreName, final String cmHandle,
-                                                                      @Valid final Object body,
+    public ResponseEntity<Object> patchResourceDataRunningForCmHandle(final String datastoreName, final String cmHandle,
+                                                                      @NotNull @Valid final String resourceIdentifier, 
+                                                                      @Valid final Object body, 
                                                                       final String contentType) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
     }
-
+    
     @Override
     public ResponseEntity<Object> queryResourceDataForCmHandle(final String datastoreName, final String cmHandle,
                                                                @Valid final String cpsPath, @Valid final String options,
@@ -218,9 +218,10 @@ public class NetworkCmProxyStubController implements NetworkCmProxyApi {
     }
 
     @Override
-    public ResponseEntity<Object> updateResourceDataRunningForCmHandle(@NotNull @Valid final String resourceIdentifier,
-                                                                       final String datastoreName,
-                                                                       final String cmHandle, @Valid final Object body,
+    public ResponseEntity<Object> updateResourceDataRunningForCmHandle(final String datastoreName, 
+                                                                       final String cmHandle, 
+                                                                       @NotNull @Valid final String resourceIdentifier, 
+                                                                       @Valid final Object body,
                                                                        final String contentType) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
diff --git a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/SampleCpsNcmpClientSpec.groovy b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/SampleCpsNcmpClientSpec.groovy
new file mode 100644
index 0000000000..b36e25ada0
--- /dev/null
+++ b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/SampleCpsNcmpClientSpec.groovy
@@ -0,0 +1,82 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2023 Nordix Foundation.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+package org.onap.cps.ncmp.rest.stub
+
+import org.onap.cps.ncmp.api.impl.operations.DatastoreType
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.boot.autoconfigure.EnableAutoConfiguration
+import org.springframework.boot.test.context.SpringBootContextLoader
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.boot.test.web.client.TestRestTemplate
+import org.springframework.boot.test.web.server.LocalServerPort
+import org.springframework.http.HttpStatus
+import org.springframework.test.context.ActiveProfiles
+import org.springframework.test.context.ContextConfiguration
+
+import com.fasterxml.jackson.core.JsonProcessingException
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.JsonMappingException
+import com.fasterxml.jackson.databind.ObjectMapper
+
+import spock.lang.Shared
+import spock.lang.Specification
+
+@SpringBootTest(classes = TestApplication.class, webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@ActiveProfiles("test")
+class SampleCpsNcmpClientSpec extends Specification {
+
+    static final String CM_HANDLE = "anything"
+
+    static final String DATA_STORE_NAME = DatastoreType.PASSTHROUGH_OPERATIONAL.getDatastoreName()
+
+    @LocalServerPort
+    def port
+
+    final def testRestTemplate = new TestRestTemplate()
+
+    @Value('${rest.api.ncmp-stub-base-path}')
+    def stubBasePath
+
+    @Autowired
+    ObjectMapper objectMapper
+
+    def 'Test the invocation of the stub API' () throws JsonMappingException, JsonProcessingException {
+
+        when: 'Get resource data for cm handle URL is invoked'
+            def url = "${getBaseUrl()}/v1/ch/${CM_HANDLE}/data/ds/${DATA_STORE_NAME}?resourceIdentifier=parent&options=(a=1,b=2)"
+            def response = testRestTemplate.getForEntity(url, String.class)
+        then: 'Response is OK'
+            response.getStatusCode() == HttpStatus.OK
+
+        and: 'Response body contains customized stub response that contains correct bookstore category code'
+            def typeRef = new TypeReference<HashMap<String, Object>>() {}
+            def map = objectMapper.readValue(response.getBody(), typeRef)
+            def obj1 = (Map<String, Object>) map.get("stores:bookstore")
+            def obj2 = (List<Object>) obj1.get("categories")
+            def obj3 = (Map<String, Object>) obj2.iterator().next()
+
+            assert obj3.get("code") == "02"
+    }
+
+    def String getBaseUrl() {
+        return "http://localhost:" + port + stubBasePath
+    }
+}
diff --git a/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/TestApplication.groovy b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/TestApplication.groovy
new file mode 100644
index 0000000000..79384239a6
--- /dev/null
+++ b/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/TestApplication.groovy
@@ -0,0 +1,28 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2023 Nordix Foundation.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+package org.onap.cps.ncmp.rest.stub
+
+import org.springframework.boot.autoconfigure.SpringBootApplication
+import org.springframework.context.annotation.ComponentScan
+
+@SpringBootApplication
+@ComponentScan(basePackages = ["org.onap.cps.ncmp.rest.stub", "org.onap.cps.ncmp.rest.stub.controller", "org.onap.cps.ncmp.rest.api"])
+class TestApplication {
+}
diff --git a/docs/cps-stubs.rst b/docs/cps-stubs.rst
index e41fe174ec..00577eb0d9 100644
--- a/docs/cps-stubs.rst
+++ b/docs/cps-stubs.rst
@@ -13,21 +13,108 @@ CPS Stubs
 .. toctree::
    :maxdepth: 1
 
-Currently stubs are only provided for the CPS-NCMP interface.
+NCMP Stubs
+==========
+
+The CPS NCMP stub module provides the capability to create dynamic and customizable stubs, offering control over the responses generated for each endpoint. This capability ensures that client interactions adhere to a specified NCMP interface, enabling comprehensive testing and validation of your applications.
+
+The NCMP stub RestController is an extended implementation of the actual NCMP interface. It can be deployed as part of the application JAR or within a SpringBootTest JUnit environment, allowing you to define dynamic responses for each endpoint and  allowing testing against real stub interfaces.
 
 Prerequisites
 =============
-t.b.d.
+
+Ensure you meet the following prerequisites:
+
+1. **Required Java Installation:**
+   
+   Ensure that you have the required Java installed on your system. 
+
+2. **Access to Gerrit and Maven Installation (for building CPS project locally):**
+
+   - Ensure you have access to the ONAP Gerrit repository.
+   
+   - If you plan to build the CPS project locally, make sure you have Maven installed. 
 
 Method 1: Running Stubs as an Application
 =========================================
-t.b.d.
+
+Follow these steps to run the CPS-NCMP stub application:
+
+1. **Download Application Jar:**
+
+   You can obtain the CPS-NCMP stub application jar in one of the following ways:
+
+   - **Option 1: Download from Nexus Repository:**
+
+     Download the application jar from the Nexus repository at `https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/`_.
+
+   - **Option 2: Build Locally:**
+
+     To build the CPS project locally, navigate to the project's root directory. Once there, you can build the project using :code:`mvn clean install`, and the application CPS-NCMP stub application jar can be found in the following location:
+
+     ::
+
+       cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-app/target/
+
+2. **Run the Application:**
+
+   After obtaining the application jar, use the following command to run it:
+
+   .. code-block:: bash
+
+      java -jar ./cps-ncmp-rest-stub-app-<VERSION>.jar
+
+   Replace ``<VERSION>`` with the actual version number of the application jar.
+
+This will start the CPS-NCMP stub application, and you can interact with it as needed.
+
+.. _`https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/`: https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/
 
 Method 2: Using Stubs in Unit Tests
 ===================================
-t.b.d.
+1. **Add Dependency to pom.xml:**
 
+   To include the required module in your project, add the following dependency to your `pom.xml` file:
 
-NCMP Stubs
-==========
-t.b.d.
+   .. code-block:: xml
+
+      <dependency>
+        <groupId>org.onap.cps</groupId>
+        <artifactId>cps-ncmp-rest-stub-service</artifactId>
+        <version>VERSION</version>
+     </dependency>
+
+   Replace ``VERSION`` with the actual version number.
+
+2. **Using Custom Response Objects:**
+
+   If you prefer to use custom response objects instead of the built-in ones, follow these steps:
+
+   Modify the `application.yaml` file located in your project's test resources directory (`src/test/resources`).
+
+   Add the following property to the `application.yaml` file, specifying the directory that contains your custom response objects:
+   
+   .. code-block:: yaml
+
+      stub:
+          path: "/my_custom_stubs/"
+
+   **Note:** Custom response objects can be placed in the `src/test/resources` directory of your project under the directory defined in above property. Refer to the `examples <https://github.com/onap/cps/tree/master/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/resources/stubs>`_ included in the CPS source repository for reference.
+
+3. **Simple Test Code:**
+
+   You may refer to the sample test code 'SampleCpsNcmpClientSpec.groovy' in the local CPS project under the following directory:
+
+   ::
+
+     /cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/
+
+   Alternatively, you can refer to the `example <https://github.com/onap/cps/tree/master/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub>`_ included in the CPS source repository.
+
+**Custom Responses for Supported Endpoints**
+
+  Only the following endpoints are supported for the first draft. To use your custom response objects for these endpoints, create the corresponding JSON files:
+
+  - For RequestMethod.GET /v1/ch/{cm-handle}/data/ds/{datastore-name}, create "passthrough-operational-example.json".
+
+  - For RequestMethod.POST /v1/ch/searches, create "cmHandlesSearch.json".