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

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

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

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

@@ -34,7 +34,7 @@ public class MgmtTargetAssignmentRequestBody {
     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")
+    @Schema(description = "Importance of the assignment", 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")

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

@@ -27,8 +27,7 @@
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
-@Schema(
-        description = """
+@Schema(description = """
     **_links**:
     * **mandatorymodules** - Link to mandatory software modules types in this distribution set type
     * **optionalmodules** - Link to optional software modules types in this distribution set type

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

@@ -9,6 +9,7 @@
  */
 package org.eclipse.hawkbit.mgmt.json.model.rollout;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import org.eclipse.hawkbit.mgmt.json.model.MgmtNamedEntity;
@@ -25,8 +26,16 @@
 @JsonIgnoreProperties(ignoreUnknown = true)
 public abstract class AbstractMgmtRolloutConditionsEntity extends MgmtNamedEntity {
 
+    @Schema(description = "The success condition which takes in place to evaluate if a rollout group is successful " +
+            "and so the next group can be started")
     private MgmtRolloutCondition successCondition;
+
+    @Schema(description = "The success action which takes in place to execute in case the success action is fulfilled")
     private MgmtRolloutSuccessAction successAction;
+
+    @Schema(description = "The error condition which takes in place to evaluate if a rollout group encounter errors")
     private MgmtRolloutCondition errorCondition;
+
+    @Schema(description = "The error action which is executed if the error condition is fulfilled")
     private MgmtRolloutErrorAction errorAction;
-}
+}

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

@@ -26,12 +26,14 @@ public enum Condition {
         THRESHOLD
     }
 
+    @Schema(description = "The type of the condition")
     private Condition condition = Condition.THRESHOLD;
-    @Schema(example = "50")
+    @Schema(description = "The expression according to the condition, e.g. the value of threshold in percentage",
+            example = "50")
     private String expression = "100";
 
     public MgmtRolloutCondition(final Condition condition, final String expression) {
         this.condition = condition;
         this.expression = expression;
     }
-}
+}

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

@@ -29,8 +29,9 @@ public enum ErrorAction {
         PAUSE
     }
 
+    @Schema(description = "The error action to execute")
     private ErrorAction action = ErrorAction.PAUSE;
-    @Schema(example = "80")
+    @Schema(description = "The expression for the error action", example = "80")
     private String expression;
 
     /**

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

@@ -29,47 +29,130 @@
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(description = """
+    **_links**:
+    * **start** - Link to start the rollout in sync mode
+    * **pause** - Link to pause a running rollout
+    * **triggerNextGroup** - Link for triggering next rollout group on a running rollout
+    * **resume** - Link to resume a paused rollout
+    * **groups** - Link to retrieve the groups a rollout
+    * **approve** - Link to approve a rollout
+    * **deny** - Link to deny a rollout
+    * **distributionset** - The link to the distribution set
+    """, example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408568812,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408568812,
+      "name" : "exampleRollout",
+      "description" : "Rollout for all named targets",
+      "targetFilterQuery" : "id==targets-*",
+      "distributionSetId" : 6,
+      "status" : "creating",
+      "totalTargets" : 20,
+      "totalTargetsPerStatus" : {
+        "running" : 0,
+        "notstarted" : 20,
+        "scheduled" : 0,
+        "cancelled" : 0,
+        "finished" : 0,
+        "error" : 0
+      },
+      "totalGroups" : 5,
+      "startAt" : 1682408570791,
+      "forcetime" : 1682408571791,
+      "deleted" : false,
+      "type" : "forced",
+      "_links" : {
+        "start" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/start"
+        },
+        "pause" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/pause"
+        },
+        "resume" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/resume"
+        },
+        "triggerNextGroup" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/triggerNextGroup"
+        },
+        "approve" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/approve"
+        },
+        "deny" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/deny"
+        },
+        "groups" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6/deploygroups?offset=0&limit=50"
+        },
+        "distributionset" : {
+          "href" : "https://management-api.host.com/rest/v1/distributionsets/6",
+          "name" : "bd3a71cb-6c8f-445c-adbb-e221414dcd96:1.0"
+        },
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/rollouts/6"
+        }
+      },
+      "id" : 6
+    }""")
 public class MgmtRolloutResponseBody extends MgmtNamedEntity {
 
-    @Schema(example = "controllerId==exampleTarget*")
+    @Schema(description = "Target filter query language expression", example = "controllerId==exampleTarget*")
     private String targetFilterQuery;
-    @Schema(example = "2")
+
+    @Schema(description = "The ID of distribution set of this rollout", example = "2")
     private Long distributionSetId;
+
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "2")
+    @Schema(description = "Rollout id", example = "2")
     private Long rolloutId;
+
     @JsonProperty(required = true)
-    @Schema(example = "ready")
+    @Schema(description = "The status of this rollout", example = "ready")
     private String status;
+
     @JsonProperty(required = true)
-    @Schema(example = "20")
+    @Schema(description = "The total targets of a rollout", example = "20")
     private Long totalTargets;
+
     @Setter(AccessLevel.NONE)
     @JsonProperty
+    @Schema(description = "The total targets per status")
     private Map<String, Long> totalTargetsPerStatus;
+
     @JsonProperty
-    @Schema(example = "5")
+    @Schema(description = "The total number of groups created by this rollout", example = "5")
     private Integer totalGroups;
+
     @JsonProperty
-    @Schema(example = "1691065753136")
+    @Schema(description = "Start at timestamp of Rollout", example = "1691065753136")
     private Long startAt;
+
     @JsonProperty
-    @Schema(example = "1691065762496")
+    @Schema(description = "Forcetime in milliseconds", example = "1691065762496")
     private Long forcetime;
+
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "Deleted flag, used for soft deleted entities", example = "false")
     private boolean deleted;
+
     @JsonProperty
+    @Schema(description = "The type of this rollout")
     private MgmtActionType type;
+
     @JsonProperty
-    @Schema(example = "400")
+    @Schema(description = "Weight of the resulting Actions", example = "400")
     private Integer weight;
+
     @JsonProperty
-    @Schema(example = "true")
+    @Schema(description = "If this rollout is dynamic or static", example = "true")
     private boolean dynamic;
+
     @JsonProperty
     @Schema(example = "Approved remark.")
     private String approvalRemark;
+
     @JsonProperty
     @Schema(example = "exampleUsername")
     private String approveDecidedBy;
@@ -81,4 +164,4 @@ public void addTotalTargetsPerStatus(final String status, final Long totalTarget
 
         totalTargetsPerStatus.put(status, totalTargetCountByStatus);
     }
-}
+}

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

@@ -31,27 +31,69 @@
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(example = """
+    {
+      "distributionSetId" : 6,
+      "targetFilterQuery" : "id==targets-*",
+      "description" : "Rollout for all named targets",
+      "amountGroups" : 5,
+      "type" : "forced",
+      "successCondition" : {
+        "condition" : "THRESHOLD",
+        "expression" : "50"
+      },
+      "successAction" : {
+        "expression" : "",
+        "action" : "NEXTGROUP"
+      },
+      "name" : "exampleRollout",
+      "forcetime" : 1682408571791,
+      "errorAction" : {
+        "expression" : "",
+        "action" : "PAUSE"
+      },
+      "confirmationRequired" : false,
+      "errorCondition" : {
+        "condition" : "THRESHOLD",
+        "expression" : "80"
+      },
+      "startAt" : 1682408570791
+    }""")
 public class MgmtRolloutRestRequestBody extends AbstractMgmtRolloutConditionsEntity {
 
-    @Schema(example = "id==targets-*")
+    @Schema(description = "Target filter query language expression", example = "id==targets-*")
     private String targetFilterQuery;
-    @Schema(example = "6")
+
+    @Schema(description = "The ID of distributionset of this rollout", example = "6")
     private long distributionSetId;
-    @Schema(example = "5")
+
+    @Schema(description = "The amount of groups the rollout should split targets into", example = "5")
     private Integer amountGroups;
-    @Schema(example = "1691065781929")
+
+    @Schema(description = "Forcetime in milliseconds", example = "1691065781929")
     private Long forcetime;
-    @Schema(example = "1691065780929")
+
+    @Schema(description = "Start at timestamp of Rollout", example = "1691065780929")
     private Long startAt;
+
     @JsonProperty
-    @Schema(example = "400")
+    @Schema(description = "Weight of the resulting Actions", example = "400")
     private Integer weight;
+
     @JsonProperty
     @Schema(example = "true")
     private boolean dynamic;
+
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = """
+        (Available with user consent flow active) If the confirmation is required for this rollout. Value will be used
+        if confirmation options are missing in the rollout group definitions. Confirmation is required per default""",
+            example = "false")
     private Boolean confirmationRequired;
+
+    @Schema(description = "The type of this rollout")
     private MgmtActionType type;
+
+    @Schema(description = "The list of group definitions")
     private List<MgmtRolloutGroup> groups;
-}
+}

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

@@ -12,6 +12,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
@@ -25,8 +26,10 @@ public enum SuccessAction {
         NEXTGROUP
     }
 
+    @Schema(description = "The success action to execute")
     private SuccessAction action = SuccessAction.NEXTGROUP;
-    private String expression = null;
+    @Schema(description = "The expression for the success action")
+    private String expression;
 
     public MgmtRolloutSuccessAction(final SuccessAction action, final String expression) {
         this.action = action;

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

@@ -26,10 +26,14 @@
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtRolloutGroup extends AbstractMgmtRolloutConditionsEntity {
 
-    @Schema(example = "controllerId==exampleTarget*")
+    @Schema(description = "The name of the entity", example = "controllerId==exampleTarget*")
     private String targetFilterQuery;
-    @Schema(example = "20.0")
+
+    @Schema(description = "Percentage of remaining and matching targets that should be added to this group",
+            example = "20.0")
     private Float targetPercentage;
-    @Schema(example = "false")
+
+    @Schema(description = "(Available with user consent flow active) If the confirmation is required for this " +
+            "rollout group. Confirmation is required per default", example = "false")
     private Boolean confirmationRequired;
 }