Added OpenAPI documentation

Signed-off-by: Alberto Codutti <alberto.codutti@eurotech.com>
eclipse-kapua · Mar 4, 2021 · 7466d49 · 7466d49
1 parent 6d46007
commit 7466d49
Show file tree

Hide file tree

Showing 4 changed files with 284 additions and 1 deletion.
diff --git a/...esources/src/main/resources/openapi/deviceInventory/deviceInventory-scopeId-deviceId.yaml b/...esources/src/main/resources/openapi/deviceInventory/deviceInventory-scopeId-deviceId.yaml
@@ -0,0 +1,114 @@
+openapi: 3.0.2
+
+info:
+  title: Eclipse Kapua REST API - Inventory
+  version: '1.0'
+  contact:
+    name: Eclipse Kapua Dev Team
+    url: https://eclipse.org/kapua
+    email: kapua-dev@eclipse.org
+  license:
+    name: Eclipse Public License 2.0
+    url: https://www.eclipse.org/legal/epl-2.0
+
+paths:
+  /{scopeId}/devices/{deviceId}/inventory:
+    get:
+      tags:
+        - Device Management - Inventory
+      summary: Get the inventory from a single Device
+      operationId: deviceInventoryGet
+      parameters:
+        - $ref: '../openapi.yaml#/components/parameters/scopeId'
+        - $ref: '../device/device.yaml#/components/parameters/deviceId'
+        - $ref: '../device/device.yaml#/components/parameters/timeout'
+      responses:
+        200:
+          description: The inventory from the Device
+          content:
+            application/json:
+              schema:
+                $ref: './deviceInventory.yaml#/components/schemas/deviceInventory'
+        401:
+          $ref: '../openapi.yaml#/components/responses/unauthenticated'
+        403:
+          $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
+        404:
+          $ref: '../openapi.yaml#/components/responses/entityNotFound'
+        500:
+          $ref: '../openapi.yaml#/components/responses/kapuaError'
+  /{scopeId}/devices/{deviceId}/inventory/bundles:
+    get:
+      tags:
+        - Device Management - Inventory
+      summary: Get the bundle inventory from a single Device
+      operationId: deviceInventoryBundleGet
+      parameters:
+        - $ref: '../openapi.yaml#/components/parameters/scopeId'
+        - $ref: '../device/device.yaml#/components/parameters/deviceId'
+        - $ref: '../device/device.yaml#/components/parameters/timeout'
+      responses:
+        200:
+          description: The bundle inventory from the Device
+          content:
+            application/json:
+              schema:
+                $ref: './deviceInventory.yaml#/components/schemas/deviceInventoryBundles'
+        401:
+          $ref: '../openapi.yaml#/components/responses/unauthenticated'
+        403:
+          $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
+        404:
+          $ref: '../openapi.yaml#/components/responses/entityNotFound'
+        500:
+          $ref: '../openapi.yaml#/components/responses/kapuaError'
+  /{scopeId}/devices/{deviceId}/inventory/system:
+    get:
+      tags:
+        - Device Management - Inventory
+      summary: Get the system packages inventory from a single Device
+      operationId: deviceInventorySystemGet
+      parameters:
+        - $ref: '../openapi.yaml#/components/parameters/scopeId'
+        - $ref: '../device/device.yaml#/components/parameters/deviceId'
+        - $ref: '../device/device.yaml#/components/parameters/timeout'
+      responses:
+        200:
+          description: The system packages inventory from the Device
+          content:
+            application/json:
+              schema:
+                $ref: './deviceInventory.yaml#/components/schemas/deviceInventorySystemPackages'
+        401:
+          $ref: '../openapi.yaml#/components/responses/unauthenticated'
+        403:
+          $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
+        404:
+          $ref: '../openapi.yaml#/components/responses/entityNotFound'
+        500:
+          $ref: '../openapi.yaml#/components/responses/kapuaError'
+  /{scopeId}/devices/{deviceId}/inventory/packages:
+    get:
+      tags:
+        - Device Management - Inventory
+      summary: Get the deployment packages inventory from a single Device
+      operationId: deviceInventoryPackagesGet
+      parameters:
+        - $ref: '../openapi.yaml#/components/parameters/scopeId'
+        - $ref: '../device/device.yaml#/components/parameters/deviceId'
+        - $ref: '../device/device.yaml#/components/parameters/timeout'
+      responses:
+        200:
+          description: The deployment packages inventory from the Device
+          content:
+            application/json:
+              schema:
+                $ref: './deviceInventory.yaml#/components/schemas/deviceInventoryDeploymentPackages'
+        401:
+          $ref: '../openapi.yaml#/components/responses/unauthenticated'
+        403:
+          $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
+        404:
+          $ref: '../openapi.yaml#/components/responses/entityNotFound'
+        500:
+          $ref: '../openapi.yaml#/components/responses/kapuaError'
diff --git a/rest-api/resources/src/main/resources/openapi/deviceInventory/deviceInventory.yaml b/rest-api/resources/src/main/resources/openapi/deviceInventory/deviceInventory.yaml
@@ -0,0 +1,160 @@
+openapi: 3.0.2
+
+info:
+  title: Eclipse Kapua REST API - Device Management - Inventory
+  version: '1.0'
+  contact:
+    name: Eclipse Kapua Dev Team
+    url: https://eclipse.org/kapua
+    email: kapua-dev@eclipse.org
+  license:
+    name: Eclipse Public License 2.0
+    url: https://www.eclipse.org/legal/epl-2.0
+
+paths: { }
+
+components:
+  schemas:
+    inventoryItem:
+      type: object
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+        itemType:
+          type: string
+      example:
+        name: adduser
+        version: 3.118
+        type: DEB
+    deviceInventory:
+      type: object
+      properties:
+        inventoryItems:
+          type: array
+          items:
+            $ref: '#/components/schemas/inventoryItem'
+      example:
+        type: deviceInventory
+        inventoryItems:
+          - name: adduser
+            version: 3.118
+            type: DEB
+          - name: alsa-utils
+            version: 1.1.8-2
+            type: DEB
+    deviceInventoryBundle:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        version:
+          type: string
+        status:
+          type: string
+      example:
+        id: 0
+        name: org.eclipse.osgi
+        version: 3.16.0.v20200828-0759
+        status: ACTIVE
+    deviceInventoryBundles:
+      type: object
+      properties:
+        inventoryBundles:
+          type: array
+          items:
+            $ref: '#/components/schemas/deviceInventoryBundle'
+      example:
+        type: deviceInventoryBundles
+        inventoryBundles:
+          - id: 0
+            name: org.eclipse.osgi
+            version: 3.16.0.v20200828-0759
+            status: ACTIVE
+          - id: 1
+            name: org.eclipse.equinox.cm
+            version: 1.4.400.v20200422-1833
+            status: RESOLVED
+    deviceInventorySystemPackage:
+      type: object
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+        packageType:
+          type: string
+      example:
+        name: adduser
+        packageType: DEB
+        version: 3.118
+    deviceInventorySystemPackages:
+      type: object
+      properties:
+        systemPackages:
+          type: array
+          items:
+            $ref: '#/components/schemas/deviceInventorySystemPackage'
+      example:
+        type: deviceInventorySystemPackages
+        systemPackages:
+          - name: adduser
+            version: 3.118
+            type: DEB
+          - name: alsa-utils
+            version: 1.1.8-2
+            type: DEB
+    deviceInventoryDeploymentPackage:
+      type: object
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+        packageBundles:
+          type: array
+          items:
+            $ref: '#/components/schemas/deviceInventoryBundle'
+      example:
+        name: org.eclipse.kura.example.beacon
+        version: 1.0.500
+        packageBundles:
+          - id: 0
+            name: org.eclipse.kura.example.beacon
+            version: 1.0.500
+            status: ACTIVE
+          - id: 1
+            name: org.eclipse.kura.example.package
+            version: 1.5.400
+            status: RESOLVED
+    deviceInventoryDeploymentPackages:
+      type: object
+      properties:
+        systemPackages:
+          type: array
+          items:
+            $ref: '#/components/schemas/deviceInventoryDeploymentPackage'
+      example:
+        type: deviceInventoryDeploymentPackages
+        deploymentPackages:
+          - name: org.eclipse.kura.example.beacon
+            version: 1.0.500
+            packageBundles:
+              - id: 0
+                name: org.eclipse.kura.example.beacon
+                version: 1.0.500
+                status: ACTIVE
+              - id: 1
+                name: org.eclipse.kura.example.package
+                version: 1.5.400
+                status: RESOLVED
+          - name: org.eclipse.kura.example.heater
+            version: 1.0.500
+            packageBundles:
+              - id: 0
+                name: org.eclipse.kura.example.heater
+                version: 1.0.500
+                status: ACTIVE
diff --git a/rest-api/resources/src/main/resources/openapi/openapi.yaml b/rest-api/resources/src/main/resources/openapi/openapi.yaml
@@ -166,6 +166,15 @@ paths:
     $ref: './deviceConfiguration/deviceConfiguration-scopeId-deviceId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1configurations'
   /{scopeId}/devices/{deviceId}/configurations/{componentId}:
     $ref: './deviceConfiguration/deviceConfiguration-scopeId-deviceId-componentId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1configurations~1{componentId}'
+  ### Device Bundle ###
+  /{scopeId}/devices/{deviceId}/inventory:
+    $ref: './deviceInventory/deviceInventory-scopeId-deviceId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1inventory'
+  /{scopeId}/devices/{deviceId}/inventory/bundles:
+    $ref: './deviceInventory/deviceInventory-scopeId-deviceId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1inventory~1bundles'
+  /{scopeId}/devices/{deviceId}/inventory/system:
+    $ref: './deviceInventory/deviceInventory-scopeId-deviceId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1inventory~1system'
+  /{scopeId}/devices/{deviceId}/inventory/packages:
+    $ref: './deviceInventory/deviceInventory-scopeId-deviceId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1inventory~1packages'
   ### Device Notification ###
   /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications:
     $ref: './deviceNotification/deviceNotification-scopeId-deviceId-operationId.yaml#/paths/~1{scopeId}~1devices~1{deviceId}~1operations~1{operationId}~1notifications'

diff --git a/...pua/service/device/management/inventory/model/bundle/inventory/DeviceInventoryBundle.java b/...pua/service/device/management/inventory/model/bundle/inventory/DeviceInventoryBundle.java
@@ -25,7 +25,7 @@
  *
  * @since 1.5.0
  */
-@XmlRootElement(name = "deviceInventoryBundles")
+@XmlRootElement(name = "deviceInventoryBundle")
 @XmlAccessorType(XmlAccessType.PROPERTY)
 @XmlType(factoryClass = DeviceInventoryBundlesXmlRegistry.class, factoryMethod = "newDeviceInventoryBundle")
 public interface DeviceInventoryBundle {