X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=cps-ncmp-rest%2Fdocs%2Fopenapi%2Fcomponents.yaml;h=d45b8da28860e1880aad2fcebd313dc8ecfadbf3;hb=7090a07b05517e0a748cb82ffac8840de82c7fa5;hp=d35919da4bc8241a3ed380367c226471c05b9c80;hpb=8640868a6d2cb0a33bdd324c8078e63def9dbe16;p=cps.git

diff --git a/cps-ncmp-rest/docs/openapi/components.yaml b/cps-ncmp-rest/docs/openapi/components.yaml
index d35919da4..d45b8da28 100644
--- a/cps-ncmp-rest/docs/openapi/components.yaml
+++ b/cps-ncmp-rest/docs/openapi/components.yaml
@@ -1,6 +1,7 @@
 #  ============LICENSE_START=======================================================
-#  Copyright (C) 2021 Nordix Foundation
+#  Copyright (C) 2021-2023 Nordix Foundation
 #  Modifications Copyright (C) 2021 Pantheon.tech
+#  Modifications Copyright (C) 2022 Bell Canada
 #  ================================================================================
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -19,6 +20,7 @@
 
 components:
   schemas:
+    # Common Schemas
     ErrorMessage:
       type: object
       title: Error
@@ -29,41 +31,424 @@ components:
           type: string
         details:
           type: string
-
+    # DMI Server Exception Schema
+    DmiErrorMessage:
+      title: DMI Error Message
+      type: object
+      properties:
+        message:
+          type: string
+          example: "Bad Gateway Error Message NCMP"
+        dmi-response:
+          type: object
+          properties:
+            http-code:
+              type: integer
+              example: 400
+            body:
+              type: string
+              example: Bad Request
+    # Request Schemas
     RestDmiPluginRegistration:
       type: object
       properties:
         dmiPlugin:
           type: string
-          example: onap-dmi-plugin
+          example: my-dmi-plugin
+          default: ""
+        dmiDataPlugin:
+          type: string
+          example: my-dmi-data-plugin
+          default: ""
+        dmiModelPlugin:
+          type: string
+          example: my-dmi-model-plugin
+          default: ""
         createdCmHandles:
           type: array
           items:
-            $ref: '#/components/schemas/RestCmHandle'
+            $ref: '#/components/schemas/RestInputCmHandle'
         updatedCmHandles:
           type: array
           items:
-            $ref: '#/components/schemas/RestCmHandle'
+            $ref: '#/components/schemas/RestInputCmHandle'
+            example:
+              cmHandle: my-cm-handle
+              cmHandleProperties:
+                add-my-property: add-property
+                update-my-property: updated-property
+                delete-my-property: '~'
+              publicCmHandleProperties:
+                add-my-property: add-property
+                update-my-property: updated-property
+                delete-my-property: '~'
         removedCmHandles:
           type: array
           items:
             type: string
+          example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
+    DmiPluginRegistrationErrorResponse:
+      type: object
+      properties:
+        failedCreatedCmHandles:
+          type: array
+          items:
+            $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
+        failedUpdatedCmHandles:
+          type: array
+          items:
+            $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
+        failedRemovedCmHandles:
+          type: array
+          items:
+            $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
+    CmHandlerRegistrationErrorResponse:
+      type: object
+      properties:
+        cmHandle:
+          type: string
+          example: my-cm-handle
+        errorCode:
+          type: string
+          example: '00'
+        errorText:
+          type: string
+          example: 'Unknown error. <error-details>'
 
-    RestCmHandle:
+    RestInputCmHandle:
       required:
         - cmHandle
       type: object
       properties:
         cmHandle:
           type: string
-          example: cmHandle123
+          example: my-cm-handle
         cmHandleProperties:
-            $ref: '#/components/schemas/RestCmHandleAdditionalProperties'
-    RestCmHandleAdditionalProperties:
+          $ref: '#/components/schemas/RestCmHandleProperties'
+        publicCmHandleProperties:
+          $ref: '#/components/schemas/RestCmHandleProperties'
+    RestCmHandleProperties:
+      type: object
+      additionalProperties:
+        type: string
+        example: my-property
+
+    #Response Schemas
+    RestModuleReference:
+      type: object
+      title: Module reference details
+      properties:
+        moduleName:
+          type: string
+          example: my-module-name
+        revision:
+          type: string
+          example: my-module-revision
+
+    RestModuleDefinition:
+      type: object
+      title: Module definitions
+      properties:
+        moduleName:
+          type: string
+          example: my-module-name
+        revision:
+          type: string
+          example: 2020-09-15
+        content:
+          type: string
+          example: |
+            module stores {
+              yang-version 1.1;
+              namespace "org:onap:ccsdk:sample";
+              prefix book-store;
+              revision "2020-09-15" {
+                description
+                "Sample Model";
+              }
+            }
+
+    CmHandleQueryParameters:
+      type: object
+      title: Cm Handle query parameters for executing cm handle search
+      properties:
+        cmHandleQueryParameters:
+          type: array
+          items:
+            type: object
+            $ref: '#/components/schemas/ConditionProperties'
+        conditions:
+          deprecated: true
+          type: array
+          items:
+            type: object
+            $ref: '#/components/schemas/OldConditionProperties'
+          description: not necessary, it is just for backward compatibility
+
+    ConditionProperties:
+      properties:
+        conditionName:
+          type: string
+        conditionParameters:
+          type: array
+          items:
+            type: object
+            additionalProperties:
+              type: string
+    OldConditionProperties:
+      deprecated: true
+      properties:
+        name:
+          type: string
+        conditionParameters:
+          type: array
+          items:
+            type: object
+            $ref: '#/components/schemas/ModuleNameAsJsonObject'
+    ModuleNameAsJsonObject:
+      properties:
+        moduleName:
+          type: string
+          example: my-module
+
+    RestOutputCmHandle:
+      type: object
+      title: CM handle Details
+      properties:
+        cmHandle:
+          type: string
+          example: my-cm-handle1
+        publicCmHandleProperties:
+          $ref: '#/components/schemas/CmHandlePublicProperties'
+        state:
+          $ref: '#/components/schemas/CmHandleCompositeState'
+    CmHandlePublicProperties:
+      type: array
+      items:
         type: object
         additionalProperties:
+          type: string
+          example: Book Type
+    CmHandleCompositeState:
+      type: object
+      properties:
+        cmHandleState:
+          type: string
+          example: ADVISED
+        lockReason:
+          $ref: '#/components/schemas/lock-reason'
+        lastUpdateTime:
+          type: string
+          example: 2022-12-31T20:30:40.000+0000
+        dataSyncEnabled:
+          type: boolean
+          example: false
+        dataSyncState:
+          $ref: '#/components/schemas/dataStores'
+
+    lock-reason:
+      type: object
+      properties:
+        reason:
+          type: string
+          example: LOCKED_MISBEHAVING
+        details:
+          type: string
+          example: locked due to failure in module sync
+
+    dataStores:
+      type: object
+      properties:
+        operational:
+          $ref: '#/components/schemas/sync-state'
+        running:
+          $ref: '#/components/schemas/sync-state'
+
+    sync-state:
+      type: object
+      properties:
+        syncState:
+          type: string
+          example: NONE_REQUESTED
+        lastSyncTime:
+          type: string
+          example: 2022-12-31T20:30:40.000+0000
+
+    RestOutputCmHandlePublicProperties:
+      type: object
+      properties:
+        publicCmHandleProperties:
+          $ref: '#/components/schemas/CmHandlePublicProperties'
+
+    RestOutputCmHandleCompositeState:
+      type: object
+      properties:
+        state:
+          $ref: '#/components/schemas/CmHandleCompositeState'
+    # Data Operation Request Schemas
+    DataOperationRequest:
+      type: object
+      title: execute data operation for given array of operations
+      properties:
+        operations:
+          type: array
+          items:
+            type: object
+            $ref: '#/components/schemas/DataOperationDefinition'
+          description: contains group of data operation requests
+    DataOperationDefinition:
+      required:
+        - operation
+        - datastore
+        - operationId
+      properties:
+        operation:
+          type: string
+          example: 'read'
+        operationId:
+          type: string
+          example: '12'
+        datastore:
+          type: string
+          example: 'ncmp-datastore:passthrough-operational'
+        options:
+          type: string
+          example: '(fields=schemas/schema)'
+        resourceIdentifier:
+          type: string
+          example: 'parent/child'
+        targetIds:
+          type: array
+          items:
             type: string
-            example: system-001
+          example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
+
+  examples:
+    dataSampleRequest:
+      summary: Sample request
+      description: Sample request body
+      value:
+        test:bookstore:
+          bookstore-name: Chapters
+          categories:
+            - code: '01'
+              name: SciFi
+              books:
+                - authors:
+                    - Iain M. Banks
+                    - Ursula K. Le Guin
+            - code: '02'
+              name: kids
+              books:
+                - authors:
+                    - Philip Pullman
+
+    dataSamplePatchRequest:
+      summary: Sample patch request
+      description: Sample patch request body
+      value:
+        ietf-restconf:yang-patch:
+          patch-id: patch-1
+          edit:
+            - edit-id: edit1
+              operation: merge
+              target: /
+              value:
+                test:bookstore:
+                  bookstore-name: Chapters
+                  categories:
+                    - code: '01'
+                      name: Science
+                      books:
+                        - authors:
+                            - Author1
+                            - Author2
+                    - code: '02'
+                      name: Arts
+                      books:
+                        - authors:
+                            - Author3
+            - edit-id: edit2
+              operation: merge
+              target: /
+              value:
+                test:bookstore:
+                  bookstore-name: Novels
+                  categories:
+                    - code: '03'
+                      name: History
+                      books:
+                        - authors:
+                            - Iain M. Banks
+                            - Ursula K. Le Guin
+                    - code: '04'
+                      name: Fiction
+                      books:
+                        - authors:
+                            - Philip Pullman
+
+    dataSampleResponse:
+      summary: Sample response
+      description: Sample response for selecting 'sample 1'.
+      value:
+        bookstore:
+          categories:
+            - code: '01'
+              books:
+                - authors:
+                    - Iain M. Banks
+                    - Ursula K. Le Guin
+              name: SciFi
+            - code: '02'
+              books:
+                - authors:
+                    - Philip Pullman
+              name: kids
+
+    allCmHandleQueryParameters:
+      value:
+        cmHandleQueryParameters:
+          - conditionName: hasAllModules
+            conditionParameters:
+              - { "moduleName": "my-module-1" }
+              - { "moduleName": "my-module-2" }
+              - { "moduleName": "my-module-3" }
+          - conditionName: hasAllProperties
+            conditionParameters:
+              - { "Color": "yellow" }
+              - { "Shape": "circle" }
+              - { "Size": "small" }
+          - conditionName: cmHandleWithCpsPath
+            conditionParameters:
+              - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
+    pubPropCmHandleQueryParameters:
+      value:
+        cmHandleQueryParameters:
+          - conditionName: hasAllProperties
+            conditionParameters:
+              - { "Color": "yellow" }
+              - { "Shape": "circle" }
+              - { "Size": "small" }
+    modulesCmHandleQueryParameters:
+      value:
+        cmHandleQueryParameters:
+          - conditionName: hasAllModules
+            conditionParameters:
+              - { "moduleName": "my-module-1" }
+              - { "moduleName": "my-module-2" }
+              - { "moduleName": "my-module-3" }
+    cpsPathCmHandleStateQueryParameters:
+      value:
+        cmHandleQueryParameters:
+          - conditionName: cmHandleWithCpsPath
+            conditionParameters:
+              - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
+    cpsPathCmHandleDataSyncQueryParameters:
+      value:
+        cmHandleQueryParameters:
+          - conditionName: cmHandleWithCpsPath
+            conditionParameters:
+              - { "cpsPath": "//state[@data-sync-enabled='true']" }
 
   parameters:
     cmHandleInPath:
@@ -73,6 +458,15 @@ components:
       required: true
       schema:
         type: string
+        example: my-cm-handle
+    dataSyncEnabled:
+      name: dataSyncEnabled
+      in: query
+      description: Is used to enable or disable the data synchronization flag
+      required: true
+      schema:
+        type: boolean
+        example: true
     xpathInQuery:
       name: xpath
       in: query
@@ -91,7 +485,7 @@ components:
     includeDescendantsOptionInQuery:
       name: include-descendants
       in: query
-      description: include-descendants
+      description: Determines if descendants are included in response
       required: false
       schema:
         type: boolean
@@ -99,11 +493,24 @@ components:
     cpsPathInQuery:
       name: cps-path
       in: query
-      description: cps-path
+      description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
       required: false
       schema:
         type: string
         default: /
+      examples:
+        container cps path:
+          value: //bookstore
+        list attributes cps path:
+          value: //categories[@code=1]
+    dmiPluginIdentifierInQuery:
+      name: dmi-plugin-identifier
+      in: query
+      description: dmi-plugin-identifier
+      required: true
+      schema:
+        type: string
+        example: my-dmi-plugin
     resourceIdentifierInQuery:
       name: resourceIdentifier
       in: query
@@ -113,44 +520,57 @@ components:
       schema:
         type: string
       examples:
-        sample1:
+        sample 1:
           value:
-            resourceIdentifier: \parent\child
-        sample2:
+            resourceIdentifier: \shops\bookstore
+        sample 2:
           value:
-            resourceIdentifier: \parent\listElement[key=value]
-        sample3:
+            resourceIdentifier: \shops\bookstore\categories[@code=1]
+        sample 3:
           value:
-            resourceIdentifier: \parent\listElement[key=value]\grandChild
-        sample4:
-          value:
-            resourceIdentifier: parent=1,child=abc
-    acceptParamInHeader:
-      name: Accept
-      in: header
-      required: false
-      description: Accept parameter for response, if accept parameter is null, that means client can accept any format.
-      schema:
-        type: string
-        enum: [ application/json, application/yang-data+json ]
+            resourceIdentifier: parent=shops,child=bookstore
     optionsParamInQuery:
       name: options
       in: query
-      description: options parameter in query, it is mandatory to wrap key(s)=value(s) in parenthesis'()'.
+      description: options parameter in query, it is mandatory to wrap key(s)=value(s) in parenthesis'()'. The format of options parameter depend on the associated DMI Plugin implementation.
       required: false
       schema:
         type: string
       allowReserved: true
       examples:
-        sample1:
+        sample 1:
           value:
-            options: (key1=value1,key2=value2)
-        sample2:
+            options: (depth=3)
+        sample 2:
           value:
-            options: (key1=value1,key2=value1/value2)
-        sample3:
+            options: (fields=book)
+        sample 3:
           value:
-            options: (key1=10,key2=value2,key3=[val31;val32])
+            options: (depth=2,fields=book/authors)
+    topicParamInQuery:
+      name: topic
+      in: query
+      description: topic parameter in query.
+      required: false
+      schema:
+        type: string
+      allowReserved: true
+      examples:
+        sample 1:
+          value:
+            topic: my-topic-name
+    requiredTopicParamInQuery:
+      name: topic
+      in: query
+      description: mandatory topic parameter in query.
+      required: true
+      schema:
+        type: string
+      allowReserved: true
+      examples:
+        sample 1:
+          value:
+            topic: my-topic-name
     contentParamInHeader:
       name: Content-Type
       in: header
@@ -159,7 +579,15 @@ components:
       schema:
         type: string
         default: application/json
-
+        example: application/yang-data+json
+    datastoreName:
+      name: datastore-name
+      in: path
+      description: The type of the requested data
+      required: true
+      schema:
+        type: string
+        example: ncmp-datastore:running
 
   responses:
     NotFound:
@@ -168,36 +596,60 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 400
+            message: Not found error message
+            details: Not found error details
     Unauthorized:
       description: Unauthorized
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 401
+            message: Unauthorized error message
+            details: Unauthorized error details
     Forbidden:
       description: Forbidden
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 403
+            message: Forbidden error message
+            details: Forbidden error details
     BadRequest:
       description: Bad Request
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 400 BAD_REQUEST
+            message: Bad request error message
+            details: Bad request error details
     Conflict:
       description: Conflict
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 409 CONFLICT
+            message: Conflict error message
+            details: Conflict error details
     NotImplemented:
       description: The given path has not been implemented
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 501
+            message: Not implemented error message
+            details: Not implemented error details
     Ok:
       description: OK
       content:
@@ -206,7 +658,28 @@ components:
             type: object
     Created:
       description: Created
-      content: {}
+      content: { }
     NoContent:
       description: No Content
-      content: {}
+      content: { }
+    InternalServerError:
+      description: Internal Server Error
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessage"
+          example:
+            status: 500
+            message: Internal Server Error
+            details: Internal Server Error occurred
+    BadGateway:
+      description: Bad Gateway
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/DmiErrorMessage"
+          example:
+            message: "Bad Gateway Error Message NCMP"
+            dmi-response:
+              http-code: 400
+              body: "Bad Request"