Add Examples to DMI-Plugin API Spec

Issue-ID: CPS-784
Signed-off-by: lukegleeson <luke.gleeson@est.tech>
Change-Id: I02e450c9c14322fa9c9ac3e14807aeebdb4b9e39

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 697de1a..6e73cf5 100644 (file)
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -27,6 +27,7 @@ Features
 --------
    - `CPS-637 <https://jira.onap.org/browse/CPS-637>`_  Support Update operation for datastore pass-through running
    - `CPS-639 <https://jira.onap.org/browse/CPS-639>`_  Support Delete operation for datastore pass-through running
+   - `CPS-784 <https://jira.onap.org/browse/CPS-784>`_  Add examples to DMI-Plugin API Spec
 
 Bug Fixes
 ---------

diff --git a/openapi/components.yml b/openapi/components.yml
index cdf4c1c..aa0827a 100644 (file)
--- a/openapi/components.yml
+++ b/openapi/components.yml
@@ -16,6 +16,7 @@ components:
       properties:
         cmHandles:
           type: array
+          example: ["cmHandleId1","cmHandleId2","cmHandleId3"]
           items:
             type: string
 
@@ -37,9 +38,11 @@ components:
                 type: object
                 properties:
                   name:
-                    $ref: '#/components/schemas/name'
+                    type: string
+                    example: my-name
                   revision:
-                    $ref: '#/components/schemas/revision'
+                    type: string
+                    example: my-revision
         cmHandleProperties:
           $ref: '#/components/schemas/cmHandleProperties'
 
@@ -53,10 +56,13 @@ components:
             properties:
               moduleName:
                 type: string
+                example: my-module-name
               revision:
-                $ref: '#/components/schemas/revision'
+                type: string
+                example: my-revision
               namespace:
                 type: string
+                example: my-namespace
 
     YangResources:
       type: array
@@ -68,10 +74,13 @@ components:
       properties:
         yangSource:
           type: string
+          example: my-yang-source
         moduleName:
           type: string
+          example: my-module-name
         revision:
-          $ref: '#/components/schemas/revision'
+          type: string
+          example: my-revision
 
     DataAccessRequest:
       type: object
@@ -79,10 +88,13 @@ components:
         operation:
           type: string
           enum: [ read, create, update, delete ]
+          example: read
         dataType:
           type: string
+          example: my-data-type
         data:
           type: string
+          example: my-data
         cmHandleProperties:
           $ref: '#/components/schemas/cmHandleProperties'
 
@@ -92,60 +104,60 @@ components:
         type: string
         example: {"prop1":"value1","prop2":"value2"}
 
-    name:
-      type: string
-      example: someName
-
-    revision:
-      type: string
-      example: someRevision
-
   responses:
-    NotFound:
-      description: The specified resource was not found
+    NoContent:
+      description: No Content
+      content: {}
+    BadRequest:
+      description: Bad Request
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 400
+            message: Bad Request
+            details: The provided request is not valid
     Unauthorized:
       description: Unauthorized
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 401
+            message: Unauthorized request
+            details: This request is unauthorized
     Forbidden:
       description: Forbidden
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
-    BadRequest:
-      description: Bad Request
+          example:
+            status: 403
+            message: Request Forbidden
+            details: This request is forbidden
+    NotFound:
+      description: The specified resource was not found
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 404
+            message: Resource Not Found
+            details: The requested resource is not found
     Conflict:
       description: Conflict
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
-    Ok:
-      description: OK
-      content:
-        application/json:
-          schema:
-            type: object
-    Created:
-      description: Created
-      content:
-        text/plain:
-          schema:
-            type: string
-    NoContent:
-      description: No Content
-      content: {}
+          example:
+            status: 409
+            message: Conflicting request
+            details: The request cannot be processed as the resource is in use.
 
   parameters:
     cmHandleInPath:
@@ -155,6 +167,7 @@ components:
       required: true
       schema:
         type: string
+        example: my-cm-handle
 
     resourceIdentifierInQuery:
       name: resourceIdentifier
@@ -164,6 +177,7 @@ components:
       allowReserved: true
       schema:
         type: string
+        example: my-schema:my-node
 
     acceptParamInHeader:
       name: accept
@@ -190,4 +204,4 @@ components:
             options: (key1=value1,key2=value1/value2)
         sample3:
           value:
-            options: (key1=10,key2=value2,key3=[val31,val32])
\ No newline at end of file
+            options: (key1=10,key2=value2,key3=val31,val32)
\ No newline at end of file

diff --git a/openapi/openapi.yml b/openapi/openapi.yml
index 5c095a7..6605a2d 100644 (file)
--- a/openapi/openapi.yml
+++ b/openapi/openapi.yml
@@ -39,12 +39,7 @@ paths:
       description: Get all modules for given cm handle
       operationId: getModuleReferences
       parameters:
-        - name: cmHandle
-          in: path
-          description: The cm handle to fetch all the modules
-          required: true
-          schema:
-            type: string
+        - $ref: 'components.yml#/components/parameters/cmHandleInPath'
       requestBody:
         description: Operational body
         content:
@@ -58,15 +53,6 @@ paths:
             application/json:
               schema:
                 $ref: 'components.yml#/components/schemas/ModuleSet'
-                example: {
-                  "schemas": [
-                    {
-                      "moduleName": "example-identifier",
-                      "revision": "example-version",
-                      "namespace": "example-namespace"
-                    }
-                  ]
-                }
         '400':
           $ref: 'components.yml#/components/responses/BadRequest'
         '401':
@@ -120,7 +106,12 @@ paths:
         required: true
       responses:
         '201':
-          $ref: 'components.yml#/components/responses/Created'
+          description: Created
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: cm-handle registered successfully
         '400':
           $ref: 'components.yml#/components/responses/BadRequest'
         '401':
@@ -148,7 +139,15 @@ paths:
               $ref: 'components.yml#/components/schemas/DataAccessRequest'
       responses:
         '200':
-          $ref: 'components.yml#/components/responses/Ok'
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                example:
+                  - yangSource: my-yang-source
+                    moduleName: my-module-name
+                    revision: my-revision
         '400':
           $ref: 'components.yml#/components/responses/BadRequest'
         '401':
@@ -175,7 +174,20 @@ paths:
               $ref: 'components.yml#/components/schemas/DataAccessRequest'
       responses:
         '201':
-          $ref: 'components.yml#/components/responses/Created'
+          description: Created
+          content:
+            text/plain:
+              schema:
+                type: string
+              examples:
+                Read:
+                  value:
+                    - yangSource: my-yang-source
+                      moduleName: my-module-name
+                      revision: my-revision
+                Write:
+                  value: "Created Resource Name"
+
         '400':
           $ref: 'components.yml#/components/responses/BadRequest'
         '401':