From 5d24142fa99b4e5d1f453bd6fb2210cf2b3daa19 Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Thu, 8 Feb 2024 16:54:01 +0200 Subject: [PATCH] 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 * 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 --------- Signed-off-by: Marinov Avgustin --- .../json/model/targettype/MgmtTargetType.java | 24 +++++++++- .../MgmtTargetTypeRequestBodyPost.java | 3 +- .../MgmtTargetTypeRequestBodyPut.java | 6 +-- .../mgmt/rest/api/MgmtTargetTypeRestApi.java | 47 +++++++++++++------ 4 files changed, 60 insertions(+), 20 deletions(-) diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java index bb19a9ec1..fd4d867a5 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetType.java @@ -25,9 +25,31 @@ import org.eclipse.hawkbit.mgmt.json.model.MgmtTypeEntity; @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/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java index 772f43e6c..64583f4bf 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPost.java @@ -23,10 +23,11 @@ import org.eclipse.hawkbit.mgmt.json.model.softwaremoduletype.MgmtSoftwareModule 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 compatibledistributionsettypes; /** diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java index d8bc9f12c..a8682f2e4 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/targettype/MgmtTargetTypeRequestBodyPut.java @@ -22,14 +22,14 @@ import lombok.experimental.Accessors; 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/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java index f578ffaf9..da105c518 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtTargetTypeRestApi.java @@ -115,7 +115,8 @@ public interface MgmtTargetTypeRestApi { * * @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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * @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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * 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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * 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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * 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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * * @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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { * * @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 @@ public interface MgmtTargetTypeRestApi { 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 @@ public interface MgmtTargetTypeRestApi { MediaType.APPLICATION_JSON_VALUE }) ResponseEntity addCompatibleDistributionSets(@PathVariable("targetTypeId") final Long targetTypeId, final List distributionSetTypeIds); -} +} \ No newline at end of file