REST doc / Mgmt Target Tag - fix missed info (#1629)

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>

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

@@ -27,12 +27,14 @@ import lombok.experimental.Accessors;
 public class MgmtTagRequestBodyPut {
 
     @JsonProperty
-    @Schema(example = "rgb(0,255,0)")
+    @Schema(description = "The name of the entity", example = "Example name")
-    private String colour;
-    @JsonProperty
-    @Schema(example = "Example name")
     private String name;
+
     @JsonProperty
-    @Schema(example = "Example description")
+    @Schema(description = "The description of the entity", example = "Example description")
     private String description;
+
+    @JsonProperty
+    @Schema(description = "The colour of the entity", example = "rgb(0,255,0)")
+    private String colour;
 }

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

@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.mgmt.json.model.tag;
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import org.eclipse.hawkbit.mgmt.json.model.target.MgmtTarget;
 
@@ -29,7 +30,10 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 public class MgmtTargetTagAssigmentResult {
 
     @JsonProperty
+    @Schema(description = "Assigned targets")
     private List<MgmtTarget> assignedTargets;
+
     @JsonProperty
+    @Schema(description = "Unassigned targets")
     private List<MgmtTarget> unassignedTargets;
 }

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

@@ -60,16 +60,19 @@ public interface MgmtTargetTagRestApi {
      *         with status OK. The response is always paged. In any failure the
      *         JsonResponseExceptionHandler is handling the response.
      */
-    @Operation(summary = "Return all target tags", description = "Handles the GET request of retrieving all target tags.")
+    @Operation(summary = "Return all target tags",
+            description = "Handles the GET request of retrieving all target tags.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
+                "changed (i.e. read-only) or data volume restriction applies."),
         @ApiResponse(responseCode = "405", description = "The http request method is not allowed on the resource."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @GetMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING, produces = { MediaTypes.HAL_JSON_VALUE,
             MediaType.APPLICATION_JSON_VALUE })
@@ -105,17 +108,21 @@ public interface MgmtTargetTagRestApi {
      *
      * @return a single target tag with status OK.
      */
-    @Operation(summary = "Return target tag by id", description = "Handles the GET request of retrieving a single target tag.")
+    @Operation(summary = "Return target tag by id",
+            description = "Handles the GET request of retrieving a single target tag.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
-        @ApiResponse(responseCode = "404", description = "Target tag not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+                "changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "404", description = "Target tag 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."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @GetMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING + "/{targetTagId}", produces = {
             MediaTypes.HAL_JSON_VALUE, MediaType.APPLICATION_JSON_VALUE })
@@ -131,18 +138,23 @@ public interface MgmtTargetTagRestApi {
      *         with status code 201 - Created. The Response Body are the created
      *         target tags but without ResponseBody.
      */
-    @Operation(summary = "Create target tag(s)", description = "Handles the POST request of creating new target tag. The request body must always be a list of target tags.")
+    @Operation(summary = "Create target tag(s)", description = "Handles the POST request of creating new target tag. " +
+            "The request body must always be a list of target tags.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
+                "changed (i.e. read-only) or data volume restriction applies."),
         @ApiResponse(responseCode = "405", description = "The http request method is not allowed on the resource."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request."),
+        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another " +
-        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not supported by the server for this resource."),
+                "user in another request at the same time. You may retry your modification request."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not " +
+                "supported by the server for this resource."),
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @PostMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING, consumes = { MediaTypes.HAL_JSON_VALUE,
             MediaType.APPLICATION_JSON_VALUE }, produces = { MediaTypes.HAL_JSON_VALUE,
@@ -153,10 +165,8 @@ public interface MgmtTargetTagRestApi {
      *
      * Handles the PUT request of updating a single targetr tag.
      *
-     * @param targetTagId
+     * @param targetTagId the ID of the target tag
-     *            the ID of the target tag
+     * @param restTargetTagRest the request body to be updated
-     * @param restTargetTagRest
-     *            the the request body to be updated
      * @return status OK if update is successful and the updated target tag.
      */
     @Operation(summary = "Update target tag by id", description = "Handles the PUT request of updating a target tag.")
@@ -165,13 +175,18 @@ public interface MgmtTargetTagRestApi {
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
-        @ApiResponse(responseCode = "404", description = "Target tag not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+                "changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "404", description = "Target tag 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."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request."),
+        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another " +
-        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not supported by the server for this resource."),
+                "user in another request at the same time. You may retry your modification request."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not " +
+                "supported by the server for this resource."),
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @PutMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING + "/{targetTagId}", consumes = {
             MediaTypes.HAL_JSON_VALUE, MediaType.APPLICATION_JSON_VALUE }, produces = { MediaTypes.HAL_JSON_VALUE,
@@ -187,17 +202,21 @@ public interface MgmtTargetTagRestApi {
      * @return status OK if delete as successfully.
      *
      */
-    @Operation(summary = "Delete target tag by id", description = "Handles the DELETE request of deleting a single target tag.")
+    @Operation(summary = "Delete target tag by id",
+            description = "Handles the DELETE request of deleting a single target tag.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
-        @ApiResponse(responseCode = "404", description = "Target tag not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+                "changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "404", description = "Target tag 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."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @DeleteMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING + "/{targetTagId}")
     ResponseEntity<Void> deleteTargetTag(@PathVariable("targetTagId") Long targetTagId);
@@ -223,17 +242,21 @@ public interface MgmtTargetTagRestApi {
      *
      * @return the list of assigned targets.
      */
-    @Operation(summary = "Return assigned targets for tag", description = "Handles the GET request of retrieving a list of assigned targets.")
+    @Operation(summary = "Return assigned targets for tag",
+            description = "Handles the GET request of retrieving a list of assigned targets.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
-        @ApiResponse(responseCode = "404", description = "Target tag not found", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+                "changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "404", description = "Target tag 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."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @GetMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING
             + MgmtRestConstants.TARGET_TAG_TARGETS_REQUEST_MAPPING, produces = { MediaTypes.HAL_JSON_VALUE,
@@ -273,17 +296,21 @@ public interface MgmtTargetTagRestApi {
      *
      * @return the list of assigned targets and unassigned targets.
      */
-    @Operation(summary = "Toggles target tag assignment", description = "Handles the POST request of toggle target assignment. The request body must always be a list of controller ids.")
+    @Operation(summary = "Toggles target tag assignment", description = "Handles the POST request of toggle target " +
+            "assignment. The request body must always be a list of controller ids.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
+                "changed (i.e. read-only) or data volume restriction applies."),
         @ApiResponse(responseCode = "405", description = "The http request method is not allowed on the resource."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request."),
+        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another " +
-        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not supported by the server for this resource."),
+                "user in another request at the same time. You may retry your modification request."),
+        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not " +
+                "supported by the server for this resource."),
         @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
     })
     @PostMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING
@@ -303,18 +330,23 @@ public interface MgmtTargetTagRestApi {
      *
      * @return the list of assigned targets.
      */
-    @Operation(summary = "Assign target(s) to given tagId", description = "Handles the POST request of target assignment. Already assigned target will be ignored.")
+    @Operation(summary = "Assign target(s) to given tagId",
+            description = "Handles the POST request of target assignment. Already assigned target will be ignored.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
+                "changed (i.e. read-only) or data volume restriction applies."),
         @ApiResponse(responseCode = "405", description = "The http request method is not allowed on the resource."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request."),
+        @ApiResponse(responseCode = "409", description = "E.g. in case an entity is created or modified by another " +
-        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not supported by the server for this resource."),
+                "user in another request at the same time. You may retry your modification request."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "415", description = "The request was attempt with a media-type which is not " +
+                "supported by the server for this resource."),
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @PostMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING
             + MgmtRestConstants.TARGET_TAG_TARGETS_REQUEST_MAPPING, consumes = { MediaTypes.HAL_JSON_VALUE,
@@ -332,20 +364,24 @@ public interface MgmtTargetTagRestApi {
      *            the ID of the target to unassign
      * @return http status code
      */
-    @Operation(summary = "Unassign target from a given tagId", description = "Handles the DELETE request to unassign the given target.")
+    @Operation(summary = "Unassign target from a given tagId",
+            description = "Handles the DELETE request to unassign the given target.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
         @ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", 
                 content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
         @ApiResponse(responseCode = "401", description = "The request requires user authentication."),
-        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be " +
-        @ApiResponse(responseCode = "404", description = "Target not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
+                "changed (i.e. read-only) or data volume restriction applies."),
+        @ApiResponse(responseCode = "404", description = "Target 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."),
         @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json."),
-        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.")
+        @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " +
+                "and the client has to wait another second.")
     })
     @DeleteMapping(value = MgmtRestConstants.TARGET_TAG_V1_REQUEST_MAPPING
             + MgmtRestConstants.TARGET_TAG_TARGETS_REQUEST_MAPPING + "/{controllerId}")
     ResponseEntity<Void> unassignTarget(@PathVariable("targetTagId") Long targetTagId,
             @PathVariable("controllerId") String controllerId);
-}
+}