REST doc / Mgmt Software Modules - fix missed info (#1625)

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

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

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

@@ -27,17 +27,46 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(description = """
+    **_links**:
+    * **download** - Download link of the artifact
+    """, example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408572660,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408572660,
+      "hashes" : {
+        "sha1" : "70686514bec4a9f8188f88d470fb3d7999728fad",
+        "md5" : "f7c5b155e3636406cbc53c61f4692637",
+        "sha256" : "efbbd71e3aa3c1db9ff3905c81f1220adb0e5db3c5438732eedf98ab006ca742"
+      },
+      "providedFilename" : "origFilename",
+      "size" : 11,
+      "_links" : {
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremodules/1/artifacts/1"
+        },
+        "download" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremodules/1/artifacts/1/download"
+        }
+      },
+      "id" : 1
+    }""")
 public class MgmtArtifact extends MgmtBaseEntity {
 
     @JsonProperty("id")
-    @Schema(example = "3")
+    @Schema(description = "Artifact id", example = "3")
     private Long artifactId;
+
     @JsonProperty
     private MgmtArtifactHash hashes;
+
     @JsonProperty
     @Schema(example = "file1")
     private String providedFilename;
+
     @JsonProperty
-    @Schema(example = "3")
+    @Schema(description = "Size of the artifact", example = "3")
     private Long size;
 }

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

@@ -26,13 +26,13 @@ import lombok.ToString;
 public class MgmtArtifactHash {
 
     @JsonProperty
-    @Schema(example = "2d86c2a659e364e9abba49ea6ffcd53dd5559f05")
+    @Schema(description = "SHA1 hash of the artifact", example = "2d86c2a659e364e9abba49ea6ffcd53dd5559f05")
     private String sha1;
     @JsonProperty
-    @Schema(example = "0d1b08c34858921bc7c662b228acb7ba")
+    @Schema(description = "MD5 hash of the artifact.", example = "0d1b08c34858921bc7c662b228acb7ba")
     private String md5;
     @JsonProperty
-    @Schema(example = "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615")
+    @Schema(description = "SHA256 hash of the artifact", example = "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615")
     private String sha256;
 
     /**

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

@@ -26,25 +26,66 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(description = """
+    **_links**:
+    * **type** - The software module type of the entity
+    * **artifacts** - List of artifacts of given software module
+    * **metadata** - List of metadata
+    """, example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408572790,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408572791,
+      "name" : "os",
+      "description" : "a description",
+      "version" : "1.0",
+      "type" : "os",
+      "typeName" : "OS",
+      "vendor" : "Vendor Limited, California",
+      "deleted" : false,
+      "encrypted" : false,
+      "_links" : {
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremodules/6"
+        },
+        "artifacts" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremodules/6/artifacts"
+        },
+        "type" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremoduletypes/13"
+        },
+        "metadata" : {
+          "href" : "https://management-api.host.com/rest/v1/softwaremodules/6/metadata?offset=0&limit=50"
+        }
+      },
+      "id" : 6
+    }""")
 public class MgmtSoftwareModule extends MgmtNamedEntity {
 
     @JsonProperty(value = "id", required = true)
     @Schema(description = "The technical identifier of the entity", example = "6")
     private Long moduleId;
+
     @JsonProperty(required = true)
     @Schema(description = "Package version", example = "1.0.0")
     private String version;
+
     @JsonProperty(required = true)
     @Schema(description = "The software module type of the entity", example = "os")
     private String type;
+
     @Schema(description = "The software module type name of the entity", example = "OS")
     private String typeName;
+
     @JsonProperty
     @Schema(description = "The software vendor", example = "Vendor Limited, California")
     private String vendor;
+
     @JsonProperty
     @Schema(description = "If the software module is deleted", example = "false")
     private boolean deleted;
+
     @JsonProperty
     @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/softwaremodule/MgmtSoftwareModuleMetadata.java

@@ -25,12 +25,15 @@ import lombok.Data;
 public class MgmtSoftwareModuleMetadata {
 
     @JsonProperty(required = true)
-    @Schema(example = "someKnownKey")
+    @Schema(description = "Metadata property key", example = "someKnownKey")
     private String key;
+
     @JsonProperty
-    @Schema(example = "someKnownValue")
+    @Schema(description = "Metadata property value", example = "someKnownValue")
     private String value;
+
     @JsonProperty
-    @Schema(example = "false")
+    @Schema(description = "Metadata property is visible to targets as part of software update action",
+            example = "false")
     private boolean targetVisible;
 }

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

@@ -81,10 +81,28 @@ public interface MgmtRolloutRestApi {
     @GetMapping(value = MgmtRestConstants.ROLLOUT_V1_REQUEST_MAPPING, produces = { MediaTypes.HAL_JSON_VALUE,
             MediaType.APPLICATION_JSON_VALUE })
     ResponseEntity<PagedList<MgmtRolloutResponseBody>> getRollouts(
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET) final int pagingOffsetParam,
+            @RequestParam(
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT) final int pagingLimitParam,
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false) final String sortParam,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET)
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false) final String rsqlParam,
+            @Schema(description = "The paging offset (default is 0)")
+            int pagingOffsetParam,
+            @RequestParam(
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT)
+            @Schema(description = "The maximum number of entries in a page (default is 50)")
+            int pagingLimitParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false)
+            @Schema(description = """
+                    The query parameter sort allows to define the sort order for the result of a query. A sort criteria
+                    consists of the name of a field and the sort direction (ASC for ascending and DESC descending).
+                    The sequence of the sort criteria (multiple can be used) defines the sort order of the entities
+                    in the result.""")
+            String sortParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false)
+            @Schema(description = """
+                    Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for
+                    available fields.""")
+            String rsqlParam,
             @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_REPRESENTATION_MODE, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_REPRESENTATION_MODE_DEFAULT) String representationModeParam);
 
     /**

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

@@ -49,18 +49,12 @@ public interface MgmtSoftwareModuleRestApi {
     /**
      * Handles POST request for artifact upload.
      *
-     * @param softwareModuleId
+     * @param softwareModuleId of the parent SoftwareModule
-     *            of the parent SoftwareModule
+     * @param file that has to be uploaded
-     * @param file
+     * @param optionalFileName to override {@link MultipartFile#getOriginalFilename()}
-     *            that has to be uploaded
+     * @param md5Sum checksum for uploaded content check
-     * @param optionalFileName
+     * @param sha1Sum checksum for uploaded content check
-     *            to override {@link MultipartFile#getOriginalFilename()}
+     * @param sha256sum checksum for uploaded content check
-     * @param md5Sum
-     *            checksum for uploaded content check
-     * @param sha1Sum
-     *            checksum for uploaded content check
-     * @param sha256Sum
-     *            checksum for uploaded content check
      *
      * @return In case all sets could successful be created the ResponseEntity
      *         with status code 201 - Created but without ResponseBody. In any
@@ -111,7 +105,9 @@ public interface MgmtSoftwareModuleRestApi {
      *         with status OK. The response is always paged. In any failure the
      *         JsonResponseExceptionHandler is handling the response.
      */
-    @Operation(summary = "Return all meta data of artifacts assigned to a software module", description = "Handles the GET request of retrieving all meta data of artifacts assigned to a software module. Required Permission: READ_REPOSITORY")
+    @Operation(summary = "Return all meta data of artifacts assigned to a software module", 
+            description = "Handles the GET request of retrieving all meta data of artifacts assigned to a " +
+                    "software module. Required Permission: READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -122,7 +118,8 @@ public interface MgmtSoftwareModuleRestApi {
                 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 = "Software Module not found ", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Software Module 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.", 
@@ -142,10 +139,8 @@ public interface MgmtSoftwareModuleRestApi {
      * Handles the GET request of retrieving a single Artifact meta data
      * request.
      *
-     * @param softwareModuleId
+     * @param softwareModuleId of the parent SoftwareModule
-     *            of the parent SoftwareModule
+     * @param artifactId of the related LocalArtifact
-     * @param artifactId
-     *            of the related LocalArtifact
      *
      * @return responseEntity with status ok if successful
      */
@@ -175,7 +170,8 @@ public interface MgmtSoftwareModuleRestApi {
     @ResponseBody ResponseEntity<MgmtArtifact> getArtifact(
             @PathVariable("softwareModuleId") final Long softwareModuleId,
             @PathVariable("artifactId") final Long artifactId,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_USE_ARTIFACT_URL_HANDLER, required = false) final Boolean useArtifactUrlHandler);
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_USE_ARTIFACT_URL_HANDLER, required = false)
+            final Boolean useArtifactUrlHandler);
 
     /**
      * Handles the DELETE request for a single SoftwareModule.
@@ -255,10 +251,28 @@ public interface MgmtSoftwareModuleRestApi {
     @GetMapping(value = MgmtRestConstants.SOFTWAREMODULE_V1_REQUEST_MAPPING, produces = { MediaTypes.HAL_JSON_VALUE,
             MediaType.APPLICATION_JSON_VALUE })
     ResponseEntity<PagedList<MgmtSoftwareModule>> getSoftwareModules(
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET) final int pagingOffsetParam,
+            @RequestParam(
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT) final int pagingLimitParam,
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false) final String sortParam,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET)
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false) final String rsqlParam);
+            @Schema(description = "The paging offset (default is 0)")
+            int pagingOffsetParam,
+            @RequestParam(
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT)
+            @Schema(description = "The maximum number of entries in a page (default is 50)")
+            int pagingLimitParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false)
+            @Schema(description = """
+                    The query parameter sort allows to define the sort order for the result of a query. A sort criteria
+                    consists of the name of a field and the sort direction (ASC for ascending and DESC descending).
+                    The sequence of the sort criteria (multiple can be used) defines the sort order of the entities
+                    in the result.""")
+            String sortParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false)
+            @Schema(description = """
+                    Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for
+                    available fields.""")
+            String rsqlParam);
 
     /**
      * Handles the GET request of retrieving a single software module.
@@ -279,7 +293,8 @@ public interface MgmtSoftwareModuleRestApi {
                 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 = "Software Module not found ", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Software Module 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.", 
@@ -435,7 +450,8 @@ public interface MgmtSoftwareModuleRestApi {
                 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 = "Software Module not found ", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Software Module 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.", 
@@ -449,10 +465,28 @@ public interface MgmtSoftwareModuleRestApi {
                     MediaType.APPLICATION_JSON_VALUE })
     ResponseEntity<PagedList<MgmtSoftwareModuleMetadata>> getMetadata(
             @PathVariable("softwareModuleId") final Long softwareModuleId,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET) final int pagingOffsetParam,
+            @RequestParam(
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT) final int pagingLimitParam,
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false) final String sortParam,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET)
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false) final String rsqlParam);
+            @Schema(description = "The paging offset (default is 0)")
+            int pagingOffsetParam,
+            @RequestParam(
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT)
+            @Schema(description = "The maximum number of entries in a page (default is 50)")
+            int pagingLimitParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false)
+            @Schema(description = """
+                    The query parameter sort allows to define the sort order for the result of a query. A sort criteria
+                    consists of the name of a field and the sort direction (ASC for ascending and DESC descending).
+                    The sequence of the sort criteria (multiple can be used) defines the sort order of the entities
+                    in the result.""")
+            String sortParam,
+            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false)
+            @Schema(description = """
+                    Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for
+                    available fields.""")
+            String rsqlParam);
 
     /**
      * Gets a single meta data value for a specific key of a software module.
@@ -475,7 +509,8 @@ public interface MgmtSoftwareModuleRestApi {
                 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 = "Software Module not found ", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Software Module 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.",