diff --git 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 index 5f72a0d23..519e81402 100644 --- 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; /** diff --git 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 index 42be5e807..c03695dfc 100644 --- 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 { @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-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 index 0c67468f1..15a785c64 100644 --- 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; } \ No newline at end of file diff --git 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 index f4c778392..a4897d26a 100644 --- 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 { + @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/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 index e3dcc3252..df610e35d 100644 --- 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; /** diff --git 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 index 959c26443..3f4d510e8 100644 --- 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; } \ No newline at end of file diff --git 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 index ef71f00a0..453e91d88 100644 --- 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 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