From f5359d6bc9063253841cc0284ca433646ca08a63 Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Thu, 8 Feb 2024 14:55:06 +0200 Subject: [PATCH] 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 --- .../json/model/artifact/MgmtArtifact.java | 33 ++++++- .../json/model/artifact/MgmtArtifactHash.java | 6 +- .../softwaremodule/MgmtSoftwareModule.java | 41 ++++++++ .../MgmtSoftwareModuleMetadata.java | 9 +- .../mgmt/rest/api/MgmtRolloutRestApi.java | 26 ++++- .../rest/api/MgmtSoftwareModuleRestApi.java | 95 +++++++++++++------ 6 files changed, 168 insertions(+), 42 deletions(-) diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifact.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifact.java index ba51044d6..cbd5a3082 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifact.java +++ b/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; } \ No newline at end of file diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifactHash.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifactHash.java index 34bd84fc5..c0135c9d8 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/artifact/MgmtArtifactHash.java +++ b/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; /** diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java index bf037d71a..af879bea9 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModule.java +++ b/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; diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModuleMetadata.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModuleMetadata.java index 7f9d1db06..560281dd5 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/softwaremodule/MgmtSoftwareModuleMetadata.java +++ b/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; } \ No newline at end of file diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtRolloutRestApi.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtRolloutRestApi.java index 8db142382..9196bb6a6 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtRolloutRestApi.java +++ b/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> 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); /** diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtSoftwareModuleRestApi.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtSoftwareModuleRestApi.java index 2f8639219..93ac8f3b4 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtSoftwareModuleRestApi.java +++ b/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 - * of the parent SoftwareModule - * @param file - * that has to be uploaded - * @param optionalFileName - * to override {@link MultipartFile#getOriginalFilename()} - * @param md5Sum - * checksum for uploaded content check - * @param sha1Sum - * checksum for uploaded content check - * @param sha256Sum - * checksum for uploaded content check + * @param softwareModuleId of the parent SoftwareModule + * @param file that has to be uploaded + * @param optionalFileName to override {@link MultipartFile#getOriginalFilename()} + * @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 - * of the parent SoftwareModule - * @param artifactId - * of the related LocalArtifact + * @param softwareModuleId of the parent SoftwareModule + * @param artifactId of the related LocalArtifact * * @return responseEntity with status ok if successful */ @@ -175,7 +170,8 @@ public interface MgmtSoftwareModuleRestApi { @ResponseBody ResponseEntity 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> getSoftwareModules( - @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); /** * 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> getMetadata( @PathVariable("softwareModuleId") final Long softwareModuleId, - @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); /** * 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.",