Merge pull request #3949 from Coduz/fix-openapiDeviceManagementAssetD…

…ocumentation Fix OpenAPI Device Management Asset documentation
eclipse-kapua · Jan 31, 2024 · ddc9808 · ddc9808
2 parents d4c749a + 3e55530
commit ddc9808
Show file tree

Hide file tree

Showing 5 changed files with 278 additions and 146 deletions.
diff --git a/.../resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId-_read.yaml b/.../resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId-_read.yaml
@@ -16,7 +16,7 @@ paths:
     post:
       tags:
         - Device Management - Asset
-      summary: Read the values for the Assets of a single Device
+      summary: Read the values for the DeviceAssets of a single Device
       operationId: deviceAssetRead
       parameters:
         - $ref: '../openapi.yaml#/components/parameters/scopeId'
@@ -27,10 +27,22 @@ paths:
         content:
           application/json:
             schema:
-              $ref: './deviceAsset.yaml#/components/schemas/deviceAssetDefinitions'
-            example:
-              deviceAsset:
-                - name: asset2
+              $ref: './deviceAsset.yaml#/components/schemas/deviceAssetsFilter'
+            examples:
+              Read all:
+                value:
+                  deviceAsset:
+                    -
+              Filter by DeviceAsset:
+                value:
+                  deviceAsset:
+                    - name: Asset-1
+              Filter by AssetChannel:
+                value:
+                  deviceAsset:
+                    - name: Asset-1
+                      channels:
+                        - name: Channel-1
         required: true
       responses:
         200:
@@ -39,6 +51,33 @@ paths:
             application/json:
               schema:
                 $ref: './deviceAsset.yaml#/components/schemas/deviceAssetValues'
+              examples:
+                Successful read:
+                  value:
+                    deviceAsset:
+                      - name: Asset-1
+                        channels:
+                          - name: Channel-1
+                            valueType: boolean
+                            value: true
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                          - name: Channel-2
+                            valueType: integer
+                            value: 8
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                Read with some errors:
+                  value:
+                    deviceAsset:
+                      - name: Asset-1
+                        channels:
+                          - name: Channel-1
+                            valueType: boolean
+                            value: true
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                          - name: Channel-2
+                            valueType: integer
+                            error: Connection failed. Unable to Connect...
+                            timestamp: '2019-09-12T14:50:24.446Z'
         401:
           $ref: '../openapi.yaml#/components/responses/unauthenticated'
         403:

diff --git a/...resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId-_write.yaml b/...resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId-_write.yaml
@@ -16,50 +16,62 @@ paths:
     post:
       tags:
         - Device Management - Asset
-      summary: Write the values for the Assets of a single Device
+      summary: Write the values for the DeviceAssets of a single Device
       operationId: deviceAssetWrite
       parameters:
         - $ref: '../openapi.yaml#/components/parameters/scopeId'
         - $ref: '../device/device.yaml#/components/parameters/deviceId'
         - $ref: '../device/device.yaml#/components/parameters/timeout'
       requestBody:
-        description: An Asset list to be updated on the desired Devica
+        description: A DeviceAsset list to be updated on the desired Device
         content:
           application/json:
             schema:
               $ref: './deviceAsset.yaml#/components/schemas/deviceAssetValues'
             example:
-              type: deviceAssets
               deviceAsset:
-                - name: asset2
+                - name: Asset-1
                   channels:
-                    - valueType: integer
-                      value: 12
-                      name: Channel-2
-                    - valueType: integer
-                      value: 80
-                      name: Channel-3
+                    - name: Channel-1
+                      valueType: boolean
+                      value: true
+                    - name: Channel-2
+                      valueType: integer
+                      value: 10
         required: true
       responses:
         200:
-          description: The updated Asset list for the desired Device with updated values
+          description: The updated DeviceAssets list for the desired Device with updated values
           content:
             application/json:
               schema:
                 $ref: './deviceAsset.yaml#/components/schemas/deviceAssetValues'
-              example:
-                type: deviceAssets
-                deviceAsset:
-                  - name: asset2
-                    channels:
-                      - valueType: integer
-                        value: 12
-                        name: Channel-2
-                        timestamp: '2019-09-12T15:40:18.278Z'
-                      - valueType: integer
-                        value: 80
-                        name: Channel-3
-                        timestamp: '2019-09-12T15:40:18.278Z'
+              examples:
+                Successful write:
+                  value:
+                    deviceAsset:
+                      - name: Asset-1
+                        channels:
+                          - name: Channel-1
+                            valueType: boolean
+                            value: true
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                          - name: Channel-2
+                            valueType: integer
+                            value: 8
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                Write with failure:
+                  value:
+                    deviceAsset:
+                      - name: Asset-1
+                        channels:
+                          - name: Channel-1
+                            valueType: boolean
+                            value: true
+                            timestamp: '2019-09-12T14:50:24.446Z'
+                          - name: Channel-2
+                            error: "Channel not available"
+                            timestamp: '2019-09-12T14:50:24.446Z'
         401:
           $ref: '../openapi.yaml#/components/responses/unauthenticated'
         403:

diff --git a/rest-api/resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId.yaml b/rest-api/resources/src/main/resources/openapi/deviceAsset/deviceAsset-scopeId-deviceId.yaml
@@ -40,42 +40,34 @@ paths:
     post:
       tags:
         - Device Management - Asset
-      summary: Get the Assets Definitions of a single Device
+      summary: Get the Assets Definitions of a single Device filtered
       operationId: deviceAssetListFiltered
       parameters:
         - $ref: '../openapi.yaml#/components/parameters/scopeId'
         - $ref: '../device/device.yaml#/components/parameters/deviceId'
         - $ref: '../device/device.yaml#/components/parameters/timeout'
       requestBody:
-        description: An object containing the list of Assets to use as a filter
+        description: An object containing the list of Assets to use as a filter. If no DeviceAsset is specified, all DeviceAsset will be read.
         content:
           application/json:
             schema:
-              $ref: './deviceAsset.yaml#/components/schemas/deviceAssetDefinitions'
-            example:
-              deviceAsset:
-                - name: asset2
+              $ref: './deviceAsset.yaml#/components/schemas/deviceAssetDefinitionsFilter'
+            examples:
+              Select all:
+                value:
+                  deviceAsset:
+                    -
+              Filtered:
+                value:
+                  deviceAsset:
+                    - name: Asset-1
       responses:
         200:
           description: The list of Assets definition of a single Device according to the filter
           content:
             application/json:
               schema:
                 $ref: './deviceAsset.yaml#/components/schemas/deviceAssetDefinitions'
-              example:
-                type: deviceAssets
-                deviceAsset:
-                  - name: asset2
-                    channels:
-                      - valueType: integer
-                        name: Channel-1
-                        mode: READ
-                      - valueType: integer
-                        name: Channel-2
-                        mode: WRITE
-                      - valueType: integer
-                        name: Channel-3
-                        mode: READ_WRITE
         401:
           $ref: '../openapi.yaml#/components/responses/unauthenticated'
         403: