Rest mme/fix openapi doc losses targettype (#1630)

* REST doc / Mgmt Target Tag - fix missed info When spring restdoc was replaces with swagger & open api some info was lost This commit returns back this info for Mgmt API - Target Tag Signed-off-by: Marinov Avgustin <Avgustin.Marinov@bosch.com> * REST doc / Mgmt Target Type - fix missed info When spring restdoc was replaces with swagger & open api some info was lost This commit returns back this info for Mgmt API - Target Type Signed-off-by: Marinov Avgustin <Avgustin.Marinov@bosch.com> --------- Signed-off-by: Marinov Avgustin <Avgustin.Marinov@bosch.com>
eclipse · Feb 8, 2024 · 5d24142 · 5d24142
1 parent c944a0d
commit 5d24142
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 20 deletions.
diff --git a/...mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java b/...mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java
@@ -25,9 +25,31 @@
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)
+@Schema(description = """
+    **_links**:
+    * **compatibledistributionsettypes** - Link to the compatible distribution set types in this target type
+    """, example = """
+    {
+      "createdBy" : "bumlux",
+      "createdAt" : 1682408564546,
+      "lastModifiedBy" : "bumlux",
+      "lastModifiedAt" : 1682408564546,
+      "name" : "TargetType",
+      "description" : "TargetType description",
+      "colour" : "#000000",
+      "_links" : {
+        "self" : {
+          "href" : "https://management-api.host.com/rest/v1/targettypes/8"
+        },
+        "compatibledistributionsettypes" : {
+          "href" : "https://management-api.host.com/rest/v1/targettypes/8/compatibledistributionsettypes"
+        }
+      },
+      "id" : 8
+    }""")
 public class MgmtTargetType extends MgmtTypeEntity {
 
     @JsonProperty(value = "id", required = true)
-    @Schema(example = "26")
+    @Schema(description = "The technical identifier of the entity", example = "26")
     private Long typeId;
 }
diff --git a/...in/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java b/...in/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java
@@ -23,10 +23,11 @@
 public class MgmtTargetTypeRequestBodyPost extends MgmtTargetTypeRequestBodyPut {
 
     @JsonProperty
-    @Schema(example = "id.t23")
+    @Schema(description = "Target type key", example = "id.t23")
     private String key;
 
     @JsonProperty
+    @Schema(description = "Array of distribution set types that are compatible to that target type")
     private List<MgmtDistributionSetTypeAssignment> compatibledistributionsettypes;
 
     /**

diff --git a/...ain/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java b/...ain/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java
@@ -22,14 +22,14 @@
 public class MgmtTargetTypeRequestBodyPut {
 
     @JsonProperty(required = true)
-    @Schema(example = "updatedTypeName")
+    @Schema(description = "The name of the entity", example = "updatedTypeName")
     private String name;
 
     @JsonProperty
-    @Schema(example = "an updated description")
+    @Schema(description = "The description of the entity", example = "an updated description")
     private String description;
 
     @JsonProperty
-    @Schema(example = "#aaafff")
+    @Schema(description = "The colour of the entity", example = "#aaafff")
     private String colour;
 }
diff --git a/...wkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java b/...wkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java
@@ -115,7 +115,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
      *
      * @return a single target type with status OK.
      */
-    @Operation(summary = "Return target type by id", description = "Handles the GET request of retrieving a single target type")
+    @Operation(summary = "Return target type by id",
+            description = "Handles the GET request of retrieving a single target type")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -126,7 +127,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
                 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 = "Target type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Target 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.", 
@@ -147,7 +149,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
      * @return status OK if delete is successful.
      *
      */
-    @Operation(summary = "Delete target type by id", description = "Handles the DELETE request for a single target type. Required Permission: DELETE_TARGET")
+    @Operation(summary = "Delete target type by id",
+            description = "Handles the DELETE request for a single target type. Required Permission: DELETE_TARGET")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -158,7 +161,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
                 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 = "Target type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Target 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.", 
@@ -179,7 +183,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
      *            the target type to be updated.
      * @return status OK if update is successful
      */
-    @Operation(summary = "Update target type by id", description = "Handles the PUT request for a single target type. Required Permission: UPDATE_TARGET")
+    @Operation(summary = "Update target type by id",
+            description = "Handles the PUT request for a single target type. Required Permission: UPDATE_TARGET")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -190,7 +195,8 @@ Query fields based on the Feed Item Query Language (FIQL). See Entity Definition
                 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 = "Target type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Target 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.", 
@@ -222,7 +228,8 @@ ResponseEntity<MgmtTargetType> updateTargetType(@PathVariable("targetTypeId") Lo
      *         ResponseBody. In any failure the JsonResponseExceptionHandler is
      *         handling the response.
      */
-    @Operation(summary = "Create target types", description = "Handles the POST request for creating new target types. The request body must always be a list of types. Required Permission: CREATE_TARGET")
+    @Operation(summary = "Create target types", description = "Handles the POST request for creating new target " +
+            "types. The request body must always be a list of types. Required Permission: CREATE_TARGET")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -233,7 +240,8 @@ ResponseEntity<MgmtTargetType> updateTargetType(@PathVariable("targetTypeId") Lo
                 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 = "Target type not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Target 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.", 
@@ -261,7 +269,9 @@ ResponseEntity<MgmtTargetType> updateTargetType(@PathVariable("targetTypeId") Lo
      *            of the TargetType.
      * @return Unpaged list of distribution set types and OK in case of success.
      */
-    @Operation(summary = "Return list of compatible distribution set types", description = "Handles the GET request of retrieving the list of compatible distribution set types in that target type. Required Permission: READ_TARGET, READ_REPOSITORY")
+    @Operation(summary = "Return list of compatible distribution set types", description = "Handles the GET request " +
+            "of retrieving the list of compatible distribution set types in that target type. " +
+            "Required Permission: READ_TARGET, READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -272,7 +282,8 @@ ResponseEntity<MgmtTargetType> updateTargetType(@PathVariable("targetTypeId") Lo
                 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 was not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution set type was 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.", 
@@ -298,7 +309,9 @@ ResponseEntity<List<MgmtDistributionSetType>> getCompatibleDistributionSets(
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Remove compatibility of distribution set type from the target type", description = "Handles the DELETE request for removing a distribution set type from a single target type. Required Permission: UPDATE_TARGET and READ_REPOSITORY")
+    @Operation(summary = "Remove compatibility of distribution set type from the target type",
+            description = "Handles the DELETE request for removing a distribution set type from a single target type. " +
+                    "Required Permission: UPDATE_TARGET and READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -309,7 +322,8 @@ ResponseEntity<List<MgmtDistributionSetType>> getCompatibleDistributionSets(
                 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 was not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution set type was 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.", 
@@ -334,7 +348,9 @@ ResponseEntity<Void> removeCompatibleDistributionSet(@PathVariable("targetTypeId
      *
      * @return OK if the request was successful
      */
-    @Operation(summary = "Adding compatibility of a distribution set type to a target type", description = "Handles the POST request for adding compatible distribution set types to a target type. Required Permission: UPDATE_TARGET and READ_REPOSITORY")
+    @Operation(summary = "Adding compatibility of a distribution set type to a target type",
+            description = "Handles the POST request for adding compatible distribution set types to a target type. " +
+                    "Required Permission: UPDATE_TARGET and READ_REPOSITORY")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
@@ -345,7 +361,8 @@ ResponseEntity<Void> removeCompatibleDistributionSet(@PathVariable("targetTypeId
                 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 was not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+        @ApiResponse(responseCode = "404", description = "Distribution set type was 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.", 
@@ -365,4 +382,4 @@ ResponseEntity<Void> removeCompatibleDistributionSet(@PathVariable("targetTypeId
                     MediaType.APPLICATION_JSON_VALUE })
     ResponseEntity<Void> addCompatibleDistributionSets(@PathVariable("targetTypeId") final Long targetTypeId,
             final List<MgmtDistributionSetTypeAssignment> distributionSetTypeIds);
-}
+}