REST doc / Mgmt Targets - fix missed info (#1628)

When spring restdoc was replaces with swagger & open api some info was lost This commit returns back this info for Mgmt API - Targets Signed-off-by: Marinov Avgustin <Avgustin.Marinov@bosch.com>
eclipse · Feb 8, 2024 · c459423 · c459423
1 parent cb88d60
commit c459423
Show file tree

Hide file tree

Showing 7 changed files with 153 additions and 55 deletions.
diff --git a/...c/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignment.java b/...c/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignment.java
@@ -20,15 +20,23 @@
 @EqualsAndHashCode(callSuper = true)
 public class MgmtDistributionSetAssignment extends MgmtId {
 
-    @Schema(example = "1691065930359")
+    @Schema(description = "Forcetime in milliseconds", example = "1691065930359")
     private long forcetime;
-    @JsonProperty(required = false)
-    @Schema(example = "23")
+
+    @JsonProperty
+    @Schema(description = "Importance of the assignment", example = "23")
     private Integer weight;
-    @JsonProperty(required = false)
-    @Schema(example = "false")
+
+    @JsonProperty
+    @Schema(description = """
+        (Available with user consent flow active) Specifies if the confirmation by the device
+        is required for this action""", example = "false")
     private Boolean confirmationRequired;
+
+    @Schema(description = "The type of the assignment")
     private MgmtActionType type;
+
+    @Schema(description = "Separation of download and install by defining a maintenance window for the installation")
     private MgmtMaintenanceWindowRequestBody maintenanceWindow;
 
     /**

diff --git a/.../main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignments.java b/.../main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignments.java
@@ -14,26 +14,20 @@
 import java.util.List;
 
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import lombok.NoArgsConstructor;
 
 /**
  * Class to hold multiple distribution set assignments. A JSON object
  * representing a single {@link MgmtDistributionSetAssignment} can be
  * deserialized to an object of this class.
  */
+@NoArgsConstructor
 @JsonDeserialize(using = MgmtDistributionSetAssignmentsDeserializer.class)
 public class MgmtDistributionSetAssignments extends ArrayList<MgmtDistributionSetAssignment> {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /**
-     * Constructor for an object that contains no distribution set assignment
-     * 
-     */
-    public MgmtDistributionSetAssignments() {
-
-    }
-
     /**
      * Constructor for an object that contains a single distribution set
      * assignment

diff --git a/...hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTarget.java b/...hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTarget.java
@@ -22,60 +22,118 @@
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
-@Schema(example = """
+@Schema(description = """
+    **_links**:
+    * **assignedDS** - Links to assigned distribution sets
+    * **installedDS** - Links to installed distribution sets
+    * **attributes** - Links to attributes of the target
+    * **actions** - Links to actions of the target
+    * **metadata** - List of metadata
+    * **targetType** - The link to the target type
+    * **autoConfirm** - The link to the detailed auto confirm state
+    """, example = """
     {
-      "createdBy" : "bumlux",
-      "createdAt" : 1682408574854,
-      "lastModifiedBy" : "bumlux",
-      "lastModifiedAt" : 1682408574863,
-      "name" : "targetExist",
-      "controllerId" : "targetExist",
-      "updateStatus" : "pending",
-      "securityToken" : "f1e3d34db13038900b7158e62a6582c8",
-      "requestAttributes" : true,
-      "_links" : {
-        "self" : {
-          "href" : "https://management-api.host.com/rest/v1/targets/targetExist"
-        }
-      }
-    }""")
+       "createdBy" : "bumlux",
+       "createdAt" : 1682408577979,
+       "lastModifiedBy" : "bumlux",
+       "lastModifiedAt" : 1682408577988,
+       "name" : "137",
+       "description" : "My name is 137",
+       "controllerId" : "137",
+       "updateStatus" : "in_sync",
+       "lastControllerRequestAt" : 1682408577978,
+       "installedAt" : 1682408577987,
+       "ipAddress" : "192.168.0.1",
+       "address" : "http://192.168.0.1",
+       "pollStatus" : {
+         "lastRequestAt" : 1682408577978,
+         "nextExpectedRequestAt" : 1682451777978,
+         "overdue" : false
+       },
+       "securityToken" : "949f1c3487125467464a960d750373c1",
+       "requestAttributes" : true,
+       "targetType" : 13,
+       "targetTypeName" : "defaultType",
+       "autoConfirmActive" : false,
+       "_links" : {
+         "self" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137"
+         },
+         "assignedDS" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/assignedDS"
+         },
+         "installedDS" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/installedDS"
+         },
+         "attributes" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/attributes"
+         },
+         "actions" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/actions?offset=0&limit=50&sort=id%3ADESC"
+         },
+         "metadata" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/metadata?offset=0&limit=50"
+         },
+         "targetType" : {
+           "href" : "https://management-api.host.com/rest/v1/targettypes/13"
+         },
+         "autoConfirm" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/137/autoConfirm"
+         }
+       }
+     }""")
 public class MgmtTarget extends MgmtNamedEntity {
 
     @JsonProperty(required = true)
-    @Schema(description = "Controller Id", example = "123")
+    @Schema(description = "Controller ID", example = "123")
     private String controllerId;
+
     @JsonProperty
     @Schema(description = "If the target is in sync", example = "in_sync")
     private String updateStatus;
+
     @JsonProperty
     @Schema(description = "Timestamp of the last controller request", example = "1691065941102")
     private Long lastControllerRequestAt;
+
     @JsonProperty
     @Schema(description = "Install timestamp", example = "1691065941155")
     private Long installedAt;
+
     @JsonProperty
-    @Schema(description = "Target IP address", example = "192.168.0.1")
+    @Schema(description = "Last known IP address of the target. Only presented if IP address of the target " +
+            "itself is known (connected directly through DDI API)", example = "192.168.0.1")
     private String ipAddress;
+
     @JsonProperty
-    @Schema(description = "Target address", example = "http://192.168.0.1")
+    @Schema(description = "The last known address URI of the target. Includes information of the target is " +
+            "connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.",
+            example = "http://192.168.0.1")
     private String address;
+
     @JsonProperty
     @Schema(description = "Poll status")
     private MgmtPollStatus pollStatus;
+
     @JsonProperty
-    @Schema(description = "Security token", example = "38e6a19932b014040ba061795186514e")
+    @Schema(description = "Pre-Shared key that allows targets to authenticate at Direct Device Integration " +
+            "API if enabled in the tenant settings", example = "38e6a19932b014040ba061795186514e")
     @ToString.Exclude
     private String securityToken;
+
     @JsonProperty
-    @Schema(description = "Request attributes", example = "true")
+    @Schema(description = "Request re-transmission of target attributes", example = "true")
     private boolean requestAttributes;
+
     @JsonProperty
-    @Schema(description = "Target type id", example = "19")
+    @Schema(description = "ID of the target type", example = "19")
     private Long targetType;
+
     @JsonProperty
-    @Schema(description = "Target type name", example = "defaultType")
+    @Schema(description = "Name of the target type", example = "defaultType")
     private String targetTypeName;
+
     @JsonProperty
-    @Schema(description = "If the auto confirm is active", example = "false")
+    @Schema(description = "Present if user consent flow active. Indicates if auto-confirm is active", example = "false")
     private Boolean autoConfirmActive;
 }
diff --git a/...t-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirm.java b/...t-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirm.java
@@ -11,6 +11,7 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
@@ -27,15 +28,34 @@
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonPropertyOrder({ "active", "initiator", "remark", "activatedAt" })
+@Schema(description = """
+    **_links**:
+    * **deactivate** - Reference link to deactivate auto confirm (present if active)
+    """, example = """
+    {
+      "active" : true,
+      "initiator" : "custom_initiator_value",
+      "remark" : "custom_remark",
+      "activatedAt" : 1682408577704,
+      "_links" : {
+        "deactivate" : {
+          "href" : "https://management-api.host.com/rest/v1/targets/137/autoConfirm/deactivate"
+        }
+      }
+    }""")
 public class MgmtTargetAutoConfirm extends RepresentationModel<MgmtTargetAutoConfirm> {
+
     @NotNull
-    @Schema(example = "true")
+    @Schema(description = "Flag if auto confirm is active", example = "true")
     private boolean active;
-    @Schema(example = "custom_initiator_value")
+
+    @Schema(description = "Initiator set on activation", example = "custom_initiator_value")
     private String initiator;
-    @Schema(example = "custom_remark")
+
+    @Schema(description = "Remark set on activation", example = "custom_remark")
     private String remark;
-    @Schema(example = "1691065938576")
+
+    @Schema(description = "Timestamp of the activation", example = "1691065938576")
     private Long activatedAt;
 
     public static MgmtTargetAutoConfirm active(final long activatedAt) {

diff --git a/...src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirmUpdate.java b/...src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirmUpdate.java
@@ -20,11 +20,12 @@
 @Data
 public class MgmtTargetAutoConfirmUpdate {
 
-    @JsonProperty(required = false)
-    @Schema(example = "custom_initiator_value")
+    @JsonProperty
+    @Schema(description = "(Optional) Initiator set on activation", example = "custom_initiator_value")
     private final String initiator;
-    @JsonProperty(required = false)
-    @Schema(example = "custom_remark")
+
+    @JsonProperty
+    @Schema(description = "(Optional) Remark set on activation", example = "custom_remark")
     private final String remark;
 
     /**

diff --git a/...t-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetRequestBody.java b/...t-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetRequestBody.java
@@ -16,23 +16,32 @@
 public class MgmtTargetRequestBody {
 
     @JsonProperty(required = true)
-    @Schema(example = "controllerName")
+    @Schema(description = "The name of the entity", example = "controllerName")
     private String name;
-    @Schema(example = "Example description of a target")
+
+    @Schema(description = "The description of the entity", example = "Example description of a target")
     private String description;
+
     @JsonProperty(required = true)
-    @Schema(example = "12345")
+    @Schema(description = "Controller ID", example = "123")
     private String controllerId;
+
     @JsonProperty
-    @Schema(example = "https://192.168.0.1")
+    @Schema(description = "The last known address URI of the target. Includes information of the target is " +
+            "connected either directly (DDI) through HTTP or indirectly (DMF) through amqp",
+            example = "https://192.168.0.1")
     private String address;
+
     @JsonProperty
-    @Schema(example = "2345678DGGDGFTDzztgf")
+    @Schema(description = "Pre-Shared key that allows targets to authenticate at Direct Device Integration API if " +
+            "enabled in the tenant settings", example = "2345678DGGDGFTDzztgf")
     private String securityToken;
+
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "Request re-transmission of target attributes", example = "true")
     private Boolean requestAttributes;
+
     @JsonProperty
-    @Schema(example = "10")
+    @Schema(description = "ID of the target type", example = "10")
     private Long targetType;
 }
diff --git a/...t/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetRestApi.java b/...t/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetRestApi.java
@@ -59,7 +59,8 @@ public interface MgmtTargetRestApi {
      *            the ID of the target to retrieve
      * @return a single target with status OK.
      */
-    @Operation(summary = "Return target by id", description = "Handles the GET request of retrieving a single target. Required Permission: READ_TARGET.")
+    @Operation(summary = "Return target by id", description = "Handles the GET request of retrieving a single target. " +
+            "Required Permission: READ_TARGET.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -70,7 +71,8 @@ public interface MgmtTargetRestApi {
                 description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or " +
                         "data volume restriction applies.", 
                 content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
-        @ApiResponse(responseCode = "404", description = "Target not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Target not found.",
+                content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
         @ApiResponse(responseCode = "405", description = "The http request method is not allowed on the resource.", 
                 content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json.", 
@@ -672,7 +674,13 @@ ResponseEntity<PagedList<MgmtActionStatus>> getActionStatusList(@PathVariable("t
     ResponseEntity<MgmtTargetAssignmentResponseBody> postAssignedDistributionSet(
             @PathVariable("targetId") String targetId,
             @Valid MgmtDistributionSetAssignments dsAssignments,
-            @RequestParam(value = "offline", required = false) boolean offline);
+            @RequestParam(value = "offline", required = false)
+            @Schema(description = """
+                    Offline update (set param to true) that is only reported but not managed by the service, e.g.
+                    defaults set in factory, manual updates or migrations from other update systems. A completed action
+                    is added to the history of the target(s). Target is set to IN_SYNC state as both assigned and
+                    installed DS are set. Note: only executed if the target has currently no running update""")
+            boolean offline);
 
     /**
      * Handles the GET request of retrieving the installed distribution set of