REST doc / Mgmt DS - fix missed info (#1621)

When spring restdoc was replaces with swagger & open api some info was lost
This commit returns back this info for Mgmt API - DistributionSets

Signed-off-by: Marinov Avgustin <Avgustin.Marinov@bosch.com>

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtMaintenanceWindowRequestBody.java

@@ -14,68 +14,29 @@ import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
 
 /**
  * Request body for maintenance window PUT/POST commands, based on a schedule
  * defined as cron expression, duration in HH:mm:ss format and time zone as
  * offset from UTC.
- *
  */
+@Data
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtMaintenanceWindowRequestBody {
+
     @JsonProperty
-    @Schema(example = "10 12 14 3 8 ? 2023")
+    @Schema(description = """
+            Schedule for the maintenance window start in quartz cron notation, such as '0 15 10 * * ? 2018'
+            for 10:15am every day during the year 2018""", example = "10 12 14 3 8 ? 2023")
     private String schedule;
 
     @JsonProperty
-    @Schema(example = "00:10:00")
+    @Schema(description = "Duration of the window, such as '02:00:00' for 2 hours", example = "00:10:00")
     private String duration;
 
     @JsonProperty
-    @Schema(example = "+00:00")
+    @Schema(description = "A time-zone offset from Greenwich/UTC, such as '+02:00'", example = "+00:00")
     private String timezone;
-
-    public String getSchedule() {
-        return schedule;
-    }
-
-    /**
-     * @param schedule
-     *            is the cron expression to be used for scheduling maintenance
-     *            window(s). Expression has 6 mandatory fields and a last
-     *            optional field: "second minute hour dayofmonth month weekday
-     *            year".
-     */
-    public void setSchedule(final String schedule) {
-        this.schedule = schedule;
-    }
-
-    public String getDuration() {
-        return duration;
-    }
-
-    /**
-     * @param duration
-     *            in HH:mm:ss format specifying the duration of a maintenance
-     *            window, for example 00:30:00 for 30 minutes.
-     */
-    public void setDuration(final String duration) {
-        this.duration = duration;
-    }
-
-    public String getTimezone() {
-        return timezone;
-    }
-
-    /**
-     * @param timezone
-     *            is the time zone specified as +/-hh:mm offset from UTC. For
-     *            example +02:00 for CET summer time and +00:00 for UTC. The
-     *            start time of a maintenance window calculated based on the
-     *            cron expression is relative to this time zone.
-     */
-    public void setTimezone(final String timezone) {
-        this.timezone = timezone;
-    }
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtMetadata.java

@@ -14,35 +14,20 @@ import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
 
 /**
  * The representation of an meta data in the REST API for POST/Create.
- *
  */
+@Data
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtMetadata {
 
     @JsonProperty(required = true)
-    @Schema(example = "someKnownKey")
+    @Schema(description = "Metadata property key", example = "someKnownKey")
     private String key;
     @JsonProperty
-    @Schema(example = "someKnownKeyValue")
+    @Schema(description = "Metadata property value", example = "someKnownKeyValue")
     private String value;
-
-    public String getKey() {
-        return key;
-    }
-
-    public void setKey(final String key) {
-        this.key = key;
-    }
-
-    public String getValue() {
-        return value;
-    }
-
-    public void setValue(final String value) {
-        this.value = value;
-    }
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtActionId.java

@@ -14,6 +14,7 @@ import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.methodOn;
 
 import java.util.Objects;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;
@@ -33,9 +34,19 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(description = """
+    {
+      "id" : 13,
+      "_links" : {
+         "self" : {
+           "href" : "https://management-api.host.com/rest/v1/targets/target2/actions/13"
+         }
+      }
+    }""")
 public class MgmtActionId extends RepresentationModel<MgmtActionId> {
 
     @JsonProperty("id")
+    @Schema(description = "ID of the action")
     private long actionId;
 
     /**

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtDistributionSet.java

@@ -18,7 +18,6 @@ import lombok.EqualsAndHashCode;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtNamedEntity;
 import org.eclipse.hawkbit.mgmt.json.model.softwaremodule.MgmtSoftwareModule;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
@@ -32,32 +31,75 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408575642,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408575643,
+      "name" : "DS",
+      "description" : "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
+      "version" : "1.0",
+      "modules" : [ {
+        "createdBy" : "bumlux",
+        "createdAt" : 1682408575640,
+        "lastModifiedBy" : "bumlux",
+        "lastModifiedAt" : 1682408575644,
+        "name" : "Firmware",
+        "description" : "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
+        "version" : "1.0.5",
+        "type" : "os",
+        "typeName" : "OS",
+        "vendor" : "vendor Limited Inc, California",
+        "deleted" : false,
+        "encrypted" : false,
+        "_links" : {
+          "self" : {
+            "href" : "https://management-api.host.com/rest/v1/softwaremodules/76"
+          }
+        },
+        "id" : 76
+    }""")
 public class MgmtDistributionSet extends MgmtNamedEntity {
 
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "51")
+    @Schema(description = "The technical identifier of the entity", example = "51")
     private Long dsId;
+
     @JsonProperty
-    @Schema(example = "1.4.2")
+    @Schema(description = "Package version", example = "1.4.2")
     private String version;
+
+    @JsonProperty
+    @Schema(description = """
+        True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled
+        when another DS is assigned (note: updatable only if DS is not yet assigned to a target)""", example = "false")
+    private boolean requiredMigrationStep;
+
+    @JsonProperty
+    @Schema(description = "The type of the distribution set", example = "test_default_ds_type")
+    private String type;
+
+    @JsonProperty
+    @Schema(description = "The type name of the distribution set",
+            example = "OS (FW) mandatory, runtime (FW) and app (SW) optional")
+    private String typeName;
+
+    @JsonProperty
+    @Schema(description = """
+        True of the distribution set software module setup is complete as defined by the
+        distribution set type""", example = "true")
+    private Boolean complete;
+
+    @JsonProperty
+    @Schema(description = "Deleted flag, used for soft deleted entities", example = "false")
+    private boolean deleted;
+
+    @JsonProperty
+    @Schema(description = "True by default and false after the distribution set is invalidated by the user",
+            example = "true")
+    private boolean valid;
+
     @JsonProperty
     private List<MgmtSoftwareModule> modules = new ArrayList<>();
-    @JsonProperty
-    @Schema(example = "false")
-    private boolean requiredMigrationStep;
-    @JsonProperty
-    @Schema(example = "test_default_ds_type")
-    private String type;
-    @JsonProperty
-    @Schema(example = "OS (FW) mandatory, runtime (FW) and app (SW) optional")
-    private String typeName;
-    @JsonProperty
-    @Schema(example = "true")
-    private Boolean complete;
-    @JsonProperty
-    @Schema(example = "false")
-    private boolean deleted;
-    @JsonProperty
-    @Schema(example = "true")
-    private boolean valid;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtDistributionSetRequestBodyPost.java

@@ -47,6 +47,6 @@ public class MgmtDistributionSetRequestBodyPost extends MgmtDistributionSetReque
     @JsonProperty
     private List<MgmtSoftwareModuleAssigment> modules;
     @JsonProperty
-    @Schema(example = "test_default_ds_type")
+    @Schema(description = "The type of the distribution set", example = "test_default_ds_type")
     private String type;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtDistributionSetRequestBodyPut.java

@@ -27,15 +27,17 @@ import lombok.experimental.Accessors;
 public class MgmtDistributionSetRequestBodyPut {
 
     @JsonProperty
-    @Schema(example = "dsOne")
+    @Schema(description = "The name of the entity", example = "dsOne")
     private String name;
     @JsonProperty
-    @Schema(example = "Description of the distribution set.")
+    @Schema(description = "The description of the entity", example = "Description of the distribution set.")
     private String description;
     @JsonProperty
-    @Schema(example = "1.0.0")
+    @Schema(description = "Package version", example = "1.0.0")
     private String version;
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = """
+        True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled
+        when another DS is assigned (note: updatable only if DS is not yet assigned to a target)""", example = "false")
     private Boolean requiredMigrationStep;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtInvalidateDistributionSetRequestBody.java

@@ -25,8 +25,9 @@ public class MgmtInvalidateDistributionSetRequestBody {
 
     @NotNull
     @JsonProperty
+    @Schema(description = "Type of cancelation for actions referring to the given distribution set")
     private MgmtCancelationType actionCancelationType;
     @JsonProperty
-    @Schema(example = "true")
+    @Schema(description = "Defines if rollouts referring to this distribution set should be canceled", example = "true")
     private boolean cancelRollouts;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtTargetAssignmentRequestBody.java

@@ -9,6 +9,7 @@
  */
 package org.eclipse.hawkbit.mgmt.json.model.distributionset;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.experimental.Accessors;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtMaintenanceWindowRequestBody;
@@ -25,11 +26,18 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtTargetAssignmentRequestBody {
 
+    @Schema(description = "The technical identifier of the entity", example = "target4")
     private String id;
+    @Schema(description = "Forcetime in milliseconds", example = "1682408575278")
     private long forcetime;
+    @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;
+    @Schema(description = "Importance of the assignment. Allowed values: 0 - 1000", example = "100")
     private Integer weight;
+    @Schema(description = "(Available with user consent flow active) Defines, if the confirmation is required for " +
+            "an action. Confirmation is required per default")
     private Boolean confirmationRequired;
 
     /**

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/distributionset/MgmtTargetAssignmentResponseBody.java

@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.mgmt.json.model.distributionset;
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import org.springframework.hateoas.RepresentationModel;
@@ -29,7 +30,11 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtTargetAssignmentResponseBody extends RepresentationModel<MgmtTargetAssignmentResponseBody> {
 
+    @Schema(description = """
+            Targets that had this distribution set already assigned (in "offline" case this includes
+            targets that have arbitrary updates running)""")
     private int alreadyAssigned;
+    @Schema(description = "The newly created actions as a result of this assignment")
     private List<MgmtActionId> assignedActions;
 
     /**

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java

@@ -14,7 +14,6 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtNamedEntity;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
@@ -30,23 +29,23 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 public class MgmtSoftwareModule extends MgmtNamedEntity {
 
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "6")
+    @Schema(description = "The technical identifier of the entity", example = "6")
     private Long moduleId;
     @JsonProperty(required = true)
-    @Schema(example = "1.0.0")
+    @Schema(description = "Package version", example = "1.0.0")
     private String version;
     @JsonProperty(required = true)
-    @Schema(example = "os")
+    @Schema(description = "The software module type of the entity", example = "os")
     private String type;
-    @Schema(example = "OS")
+    @Schema(description = "The software module type name of the entity", example = "OS")
     private String typeName;
     @JsonProperty
-    @Schema(example = "Vendor Limited, California")
+    @Schema(description = "The software vendor", example = "Vendor Limited, California")
     private String vendor;
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "If the software module is deleted", example = "false")
     private boolean deleted;
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "If the software module is encrypted", example = "false")
     private boolean encrypted;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/target/MgmtTarget.java

@@ -3,8 +3,6 @@
  */
 package org.eclipse.hawkbit.mgmt.json.model.target;
 
-import java.net.URI;
-
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
@@ -12,7 +10,6 @@ import lombok.ToString;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtNamedEntity;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtPollStatus;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
@@ -25,42 +22,60 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(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"
+        }
+      }
+    }""")
 public class MgmtTarget extends MgmtNamedEntity {
 
     @JsonProperty(required = true)
-    @Schema(example = "123")
+    @Schema(description = "Controller Id", example = "123")
     private String controllerId;
     @JsonProperty
-    @Schema(example = "in_sync")
+    @Schema(description = "If the target is in sync", example = "in_sync")
     private String updateStatus;
     @JsonProperty
-    @Schema(example = "1691065941102")
+    @Schema(description = "Timestamp of the last controller request", example = "1691065941102")
     private Long lastControllerRequestAt;
     @JsonProperty
-    @Schema(example = "1691065941155")
+    @Schema(description = "Install timestamp", example = "1691065941155")
     private Long installedAt;
     @JsonProperty
-    @Schema(example = "192.168.0.1")
+    @Schema(description = "Target IP address", example = "192.168.0.1")
     private String ipAddress;
     @JsonProperty
-    @Schema(example = "http://192.168.0.1")
+    @Schema(description = "Target address", example = "http://192.168.0.1")
     private String address;
     @JsonProperty
+    @Schema(description = "Poll status")
     private MgmtPollStatus pollStatus;
     @JsonProperty
-    @Schema(example = "38e6a19932b014040ba061795186514e")
+    @Schema(description = "Security token", example = "38e6a19932b014040ba061795186514e")
     @ToString.Exclude
     private String securityToken;
     @JsonProperty
-    @Schema(example = "true")
+    @Schema(description = "Request attributes", example = "true")
     private boolean requestAttributes;
     @JsonProperty
-    @Schema(example = "19")
+    @Schema(description = "Target type id", example = "19")
     private Long targetType;
     @JsonProperty
-    @Schema(example = "defaultType")
+    @Schema(description = "Target type name", example = "defaultType")
     private String targetTypeName;
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "If the auto confirm is active", example = "false")
     private Boolean autoConfirmActive;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targetfilter/MgmtTargetFilterQuery.java

@@ -27,25 +27,51 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.ALWAYS)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408575234,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408575234,
+      "name" : "filter1",
+      "query" : "name==a",
+      "autoAssignDistributionSet" : 16,
+      "autoAssignActionType" : null,
+      "autoAssignWeight" : null,
+      "confirmationRequired" : null,
+      "_links" : {
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/targetfilters/2"
+        }
+      },
+      "id" : 2
+    }""")
 public class MgmtTargetFilterQuery extends MgmtBaseEntity {
 
     @JsonProperty(value = "id", required = true)
     @Schema(example = "2")
     private Long filterId;
+
     @JsonProperty
     @Schema(example = "filterName")
     private String name;
+
     @JsonProperty
     @Schema(example = "name==*")
     private String query;
+
     @JsonProperty
     @Schema(example = "15")
+
     private Long autoAssignDistributionSet;
+
     @JsonProperty
     private MgmtActionType autoAssignActionType;
+
     @JsonProperty
     @Schema(example = "")
     private Integer autoAssignWeight;
+
     @JsonProperty
     @Schema(example = "false")
     private Boolean confirmationRequired;