Merge pull request #3929 from Coduz/fix-devicePackageOpenAPIDocumenta…

…tion

Fix DevicePackage OpenAPI documentation

rest-api/resources/src/main/resources/openapi/devicePackage/devicePackage-scopeId-deviceId-_download.yaml

@@ -35,8 +35,6 @@ paths:
                   uri: https://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.dp
                   name: heater
                   version: 1.0.500
-                  install: true
-                  reboot: false
               complete:
                 summary: Complete
                 description: A request with all available options used

rest-api/resources/src/main/resources/openapi/devicePackage/devicePackage-scopeId-deviceId-_uninstall.yaml

@@ -26,23 +26,22 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                name:
-                  type: string
-                version:
-                  type: string
-                reboot:
-                  type: boolean
-                rebootDelay:
-                  type: integer
-              required:
-                - name
-                - version
-            example:
-              name: org.eclipse.kura.demo.heater
-              version: 1.0.500
-        required: true
+              $ref: './devicePackage.yaml#/components/schemas/devicePackageUninstallRequest'
+            examples:
+              basic:
+                summary: Basic
+                description: A request with only required properties
+                value:
+                  name: org.eclipse.kura.demo.heater
+                  version: 1.0.500
+              complete:
+                summary: Complete
+                description: A request with all properties
+                value:
+                  name: org.eclipse.kura.demo.heater
+                  version: 1.0.500
+                  reboot: false
+                  rebootDelay: 0
       responses:
         200:
           description: The corresponding Device Management Operation to track the progress of the Device Package Uninstall Request

rest-api/resources/src/main/resources/openapi/devicePackage/devicePackage.yaml

@@ -15,23 +15,36 @@ paths: {}
 
 components:
   schemas:
+    bundleInfo:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The bundle name
+        version:
+          type: string
+          description: the bundle version
     devicePackage:
       type: object
       description: A Device Package
       properties:
         name:
           type: string
+          description: The name of the package
         version:
           type: string
+          description: The version of the package
         bundleInfos:
           type: object
+          description: The bundles of this package
           properties:
             bundleInfo:
               type: array
               items:
                 $ref: '#/components/schemas/bundleInfo'
         installDate:
           type: string
+          description: The installation date of the package
           format: 'date-time'
       example:
         name: org.eclipse.kura.demo.heater
@@ -56,44 +69,69 @@ components:
               bundleInfo:
                 - name: org.eclipse.kura.demo.heater
                   version: 1.0.300
+    devicePackageDownloadRequestFileType:
+      type: string
+      description: The type of the URI resource content
+      enum:
+        - DEPLOYMENT_PACKAGE
+        - EXECUTABLE_SCRIPT
     devicePackageDownloadRequest:
       type: object
       properties:
         uri:
           type: string
+          description: The URI to download the resource
         name:
           type: string
+          description: The name of the downloaded package
         version:
           type: string
+          description: The version of the downloaded package
         username:
           type: string
+          description: The username to use in the HTTP basic authentication when accessing the URI resource
         password:
           type: string
+          description: The password to use in the HTTP basic authentication when accessing the URI resource
         fileHash:
           type: string
+          description: The MD5 has to check resource integrity after download
         fileType:
-          type: string
+          $ref: '#/components/schemas/devicePackageDownloadRequestFileType'
         install:
           type: boolean
+          description: Whether to install or not the package after download
         reboot:
           type: boolean
+          description: Whether to reboot the device after installation of the package
         rebootDelay:
           type: integer
+          description: The delay in milliseconds to delay the reboot after installation
         advancedOptions:
           type: object
           properties:
             restart:
               type: boolean
+              description: Whether or not to resume the partial download of the URI resource. The resource is identified by name and version provided
             blockSize:
               type: integer
+              description: The block size in kBi to use while downloading the URI resource
             blockDelay:
               type: integer
+              description: The delay in ms to delay each block download of the URI resource
             blockTimeout:
               type: integer
+              description: The delay timeout to download each block of the URI resource
             notifyBlockSize:
               type: integer
+              description: The amount of kBi to download before sending a new Operation Notification to the platform
             installVerifyURI:
               type: string
+              description: The URI to download the script that can verify that the package installation has successfully completed.
+      required:
+        - uri
+        - name
+        - version
       example:
         uri: https://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.dp
         name: heater
@@ -112,10 +150,26 @@ components:
           blockTimeout: 5000
           notifyBlockSize: 256
           installVerifyURI: https://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.verifier.sh
-    bundleInfo:
+    devicePackageUninstallRequest:
       type: object
       properties:
         name:
           type: string
+          description: The package name to uninstall
         version:
           type: string
+          description: The package verson to uninstall
+        reboot:
+          type: boolean
+          description: Whether to reboot the device after uninstall of the package
+        rebootDelay:
+          type: integer
+          description: The delay in milliseconds to delay the reboot after uninstallation
+      required:
+        - name
+        - version
+      example:
+        name: org.eclipse.kura.demo.heater
+        version: 1.0.500
+        reboot: false
+        rebootDelay: 0

rest-api/resources/src/main/resources/openapi/openapi.yaml

@@ -843,8 +843,12 @@ components:
       $ref: './devicePackage/devicePackage.yaml#/components/schemas/devicePackage'
     devicePackages:
       $ref: './devicePackage/devicePackage.yaml#/components/schemas/devicePackages'
+    devicePackageDownloadRequestFileType:
+      $ref: './devicePackage/devicePackage.yaml#/components/schemas/devicePackageDownloadRequestFileType'
     devicePackageDownloadRequest:
       $ref: './devicePackage/devicePackage.yaml#/components/schemas/devicePackageDownloadRequest'
+    devicePackageUninstallRequest:
+      $ref: './devicePackage/devicePackage.yaml#/components/schemas/devicePackageUninstallRequest'
     ### Device Request Entities ###
     requestInput:
       $ref: './deviceRequest/deviceRequest.yaml#/components/schemas/requestInput'