REST doc / Mgmt DS Tags - fix missed info (#1622) (#1623)

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

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

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

@@ -19,15 +19,16 @@ import io.swagger.v3.oas.annotations.media.Schema;
 public abstract class MgmtTypeEntity extends MgmtNamedEntity {
 
     @JsonProperty(required = true)
-    @Schema(example = "id.t23")
+    @Schema(name = "Key that can be interpreted by the target", example = "id.t23")
     private String key;
 
     @JsonProperty
-    @Schema(example = "brown")
+    @Schema(description = "Colour assigned to the entity that could be used for representation purposes",
+            example = "brown")
     private String colour;
 
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "Deleted flag, used for soft deleted entities", example = "false")
     private boolean deleted;
 
     public String getKey() {

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

@@ -27,9 +27,38 @@ import org.eclipse.hawkbit.mgmt.json.model.MgmtTypeEntity;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@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
+    """, example = """
+     {
+       "createdBy" : "bumlux",
+       "createdAt" : 1682408579418,
+       "lastModifiedBy" : "bumlux",
+       "lastModifiedAt" : 1682408579459,
+       "name" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
+       "description" : "Desc1234",
+       "key" : "test_default_ds_type",
+       "deleted" : false,
+       "colour" : "rgb(86,37,99)",
+       "_links" : {
+         "self" : {
+           "href" : "https://management-api.host.com/rest/v1/distributionsettypes/14"
+         },
+         "mandatorymodules" : {
+           "href" : "https://management-api.host.com/rest/v1/distributionsettypes/14/mandatorymoduletypes"
+         },
+         "optionalmodules" : {
+           "href" : "https://management-api.host.com/rest/v1/distributionsettypes/14/optionalmoduletypes"
+         }
+       },
+       "id" : 14
+     }""")
 public class MgmtDistributionSetType extends MgmtTypeEntity {
 
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "99")
+    @Schema(description = "The technical identifier of the entity", example = "99")
     private Long moduleId;
 }

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

@@ -28,14 +28,18 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 public class MgmtDistributionSetTypeRequestBodyPost extends MgmtDistributionSetTypeRequestBodyPut {
 
     @JsonProperty(required = true)
-    @Schema(example = "Example type name")
+    @Schema(description = "The name of the entity", example = "Example type name")
     private String name;
+
     @JsonProperty(required = true)
-    @Schema(example = "Example key")
+    @Schema(description = "Functional key of the distribution set type", example = "Example key")
     private String key;
+
     @JsonProperty
+    @Schema(description = "Mandatory module type IDs")
     private List<MgmtSoftwareModuleTypeAssigment> mandatorymodules;
     @JsonProperty
+    @Schema(description = "Optional module type IDs")
     private List<MgmtSoftwareModuleTypeAssigment> optionalmodules;
 
     @Override

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

@@ -22,9 +22,9 @@ import lombok.experimental.Accessors;
 public class MgmtDistributionSetTypeRequestBodyPut {
 
     @JsonProperty
-    @Schema(example = "Example description")
+    @Schema(description = "The description of the entity", example = "Example description")
     private String description;
     @JsonProperty
-    @Schema(example = "rgb(86,37,99)")
+    @Schema(description = "The colour of the entity", example = "rgb(86,37,99)")
     private String colour;
 }

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

@@ -27,12 +27,31 @@ import org.eclipse.hawkbit.mgmt.json.model.MgmtTypeEntity;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(example = """
+    {
+      "createdBy" : "system",
+      "createdAt" : 1682408579390,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408579394,
+      "name" : "Application",
+      "description" : "Updated description.",
+      "key" : "application",
+      "maxAssignments" : 2147483647,
+      "deleted" : false,
+      "_links" : {
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremoduletypes/4"
+        }
+      },
+      "id" : 4
+    }""")
 public class MgmtSoftwareModuleType extends MgmtTypeEntity {
 
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "83")
+    @Schema(description = "The technical identifier of the entity", example = "83")
     private Long moduleId;
     @JsonProperty
-    @Schema(example = "1")
+    @Schema(description = "Software modules of that type can be assigned at this maximum number " +
+            "(e.g. operating system only once)", example = "1")
     private int maxAssignments;
 }

hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtDistributionSetTypeRestApi.java

@@ -62,7 +62,8 @@ public interface MgmtDistributionSetTypeRestApi {
      *         failure the JsonResponseExceptionHandler is handling the
      *         response.
      */
-    @Operation(summary = "Return all Distribution Set Types", description = "Handles the GET request of retrieving all distribution set types. Required Permission: READ_REPOSITORY")
+    @Operation(summary = "Return all Distribution Set Types", description = "Handles the GET request of " +
+            "retrieving all distribution set types. Required Permission: READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -127,7 +128,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -160,7 +162,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -192,7 +195,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -276,7 +280,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -301,7 +306,9 @@ public interface MgmtDistributionSetTypeRestApi {
      *            of SoftwareModuleType.
      * @return Unpaged list of module types and OK in case of success.
      */
-    @Operation(summary = "Return single mandatory Software Module Type in a Distribution Set Type", description = "Handles the GET request of retrieving the single mandatory software module type in that distribution set type. Required Permission: READ_REPOSITORY")
+    @Operation(summary = "Return single mandatory Software Module Type in a Distribution Set Type",
+            description = "Handles the GET request of retrieving the single mandatory software module type in that " +
+                    "distribution set type. Required Permission: READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -312,7 +319,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -338,7 +346,9 @@ public interface MgmtDistributionSetTypeRestApi {
      *            of SoftwareModuleType.
      * @return Unpaged list of module types and OK in case of success.
      */
-    @Operation(summary = "Return single optional Software Module Type in a Distribution Set Type", description = "Handles the GET request of retrieving the single optional software module type in that distribution set type. Required Permission: READ_REPOSITORY")
+    @Operation(summary = "Return single optional Software Module Type in a Distribution Set Type",
+            description = "Handles the GET request of retrieving the single optional software module type in that " +
+                    "distribution set type. Required Permission: READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -349,7 +359,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -373,7 +384,9 @@ public interface MgmtDistributionSetTypeRestApi {
      *            of the DistributionSetType.
      * @return Unpaged list of module types and OK in case of success.
      */
-    @Operation(summary = "Return optional Software Module Types in a Distribution Set Type", description = "Handles the GET request of retrieving the list of optional software module types in that distribution set type. Required Permission: READ_REPOSITORY")
+    @Operation(summary = "Return optional Software Module Types in a Distribution Set Type",
+            description = "Handles the GET request of retrieving the list of optional software module types in that " +
+                    "distribution set type. Required Permission: READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -384,7 +397,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -410,7 +424,9 @@ public interface MgmtDistributionSetTypeRestApi {
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Delete a mandatory module from a Distribution Set Type", description = "Handles the DELETE request for removing a software module type from a single distribution set type. Required Permission: DELETE_REPOSITORY")
+    @Operation(summary = "Delete a mandatory module from a Distribution Set Type",
+            description = "Handles the DELETE request for removing a software module type from a single " +
+                    "distribution set type. Required Permission: DELETE_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -421,7 +437,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -446,7 +463,10 @@ public interface MgmtDistributionSetTypeRestApi {
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Delete an optional module from a Distribution Set Type", description = "Handles DELETE request for removing an optional module from the distribution set type. Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
+    @Operation(summary = "Delete an optional module from a Distribution Set Type",
+            description = "Handles DELETE request for removing an optional module from the distribution set type. " +
+                    "Note that a DS type cannot be changed after it has been used by a DS. " +
+                    "Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -457,7 +477,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -482,7 +503,10 @@ public interface MgmtDistributionSetTypeRestApi {
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Add mandatory Software Module Type to a Distribution Set Type", description = "Handles the POST request for adding a mandatory software module type to a distribution set type.Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
+    @Operation(summary = "Add mandatory Software Module Type to a Distribution Set Type",
+            description = "Handles the POST request for adding a mandatory software module type to a " +
+                    "distribution set type.Note that a DS type cannot be changed after it has been used by a DS. " +
+                    "Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -493,7 +517,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -525,7 +550,10 @@ public interface MgmtDistributionSetTypeRestApi {
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Add optional Software Module Type to a Distribution Set Type", description = "Handles the POST request for adding an optional software module type to a distribution set type.Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
+    @Operation(summary = "Add optional Software Module Type to a Distribution Set Type",
+            description = "Handles the POST request for adding an optional software module type to a " +
+                    "distribution set type.Note that a DS type cannot be changed after it has been used by a DS. " +
+                    "Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters",
@@ -536,7 +564,8 @@ public interface MgmtDistributionSetTypeRestApi {
                 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 = "Distribution Set Type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution Set Type 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.",
@@ -556,5 +585,4 @@ public interface MgmtDistributionSetTypeRestApi {
                     MediaType.APPLICATION_JSON_VALUE })
     ResponseEntity<Void> addOptionalModule(@PathVariable("distributionSetTypeId") Long distributionSetTypeId,
             MgmtId smtId);
-
 }