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>
2024-02-08 15:50:19 +02:00
parent cb88d60226
commit c4594239a2
7 changed files with 153 additions and 55 deletions
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignment.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignment.java
@@ -20,15 +20,23 @@ import com.fasterxml.jackson.annotation.JsonProperty;
@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;

    /**
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignments.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtDistributionSetAssignments.java
@@ -14,26 +14,20 @@ import java.util.ArrayList;
 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
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTarget.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTarget.java
@@ -22,60 +22,118 @@ import com.fasterxml.jackson.annotation.JsonProperty;
@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;
 }
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirm.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirm.java
@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.mgmt.json.model.target;

 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 @@ import jakarta.validation.constraints.NotNull;
@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) {
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirmUpdate.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetAutoConfirmUpdate.java
@@ -20,11 +20,12 @@ import lombok.Data;
@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;

    /**
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetRequestBody.java
+++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTargetRequestBody.java
@@ -16,23 +16,32 @@ import lombok.experimental.Accessors;
 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;
 }
--- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetRestApi.java
+++ b/hawkbit-rest/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 @@ public interface MgmtTargetRestApi {
    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