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>
eclipse · Feb 8, 2024 · f5359d6 · f5359d6
1 parent b1cc868
commit f5359d6
Show file tree

Hide file tree

Showing 6 changed files with 168 additions and 42 deletions.
diff --git a/...bit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifact.java b/...bit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifact.java
@@ -27,17 +27,46 @@
 @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;
 }
diff --git a/...mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifactHash.java b/...mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifactHash.java
@@ -26,13 +26,13 @@
 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;
 
     /**

diff --git a/.../src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java b/.../src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java
@@ -26,25 +26,66 @@
 @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;

diff --git a/...n/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModuleMetadata.java b/...n/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModuleMetadata.java
@@ -25,12 +25,15 @@
 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;
 }
diff --git a/.../hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtRolloutRestApi.java b/.../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(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT) final int pagingLimitParam,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false) final String sortParam,
-            @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false) final String rsqlParam,
+            @RequestParam(
+                    value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET,
+                    defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET)
+            @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);
 
     /**