From 3808d86b33469ba1e1b822853f14a4faf0575110 Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Wed, 7 Feb 2024 16:36:15 +0200 Subject: [PATCH] REST doc / Mgmt Actions - fix missed info (#1619) When spring restdoc was replaces with swagger & open api some info was lost This commit returns back this info for Mgmt API - Actions Signed-off-by: Marinov Avgustin --- .../mgmt/json/model/MgmtBaseEntity.java | 53 ++++--------- .../mgmt/json/model/action/MgmtAction.java | 51 ++++++++++-- .../mgmt/rest/api/MgmtActionRestApi.java | 78 ++++++++++++++----- 3 files changed, 115 insertions(+), 67 deletions(-) diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java index 73f5d4bb5..1928a617b 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java @@ -25,17 +25,24 @@ import com.fasterxml.jackson.annotation.JsonProperty; @EqualsAndHashCode(callSuper = true) public abstract class MgmtBaseEntity extends RepresentationModel { - @JsonProperty - @Schema(example = "bumlux") + @JsonProperty(access = JsonProperty.Access.READ_ONLY) + @Schema(description = "Entity was originally created by (User, AMQP-Controller, anonymous etc.)", + accessMode = Schema.AccessMode.READ_WRITE, example = "bumlux") private String createdBy; - @JsonProperty - @Schema(example = "1691065905897") + + @JsonProperty(access = JsonProperty.Access.READ_ONLY) + @Schema(description = "Entity was originally created at (timestamp UTC in milliseconds)", + accessMode = Schema.AccessMode.READ_ONLY, example = "1691065905897") private Long createdAt; - @JsonProperty - @Schema(example = "bumlux") + + @JsonProperty(access = JsonProperty.Access.READ_ONLY) + @Schema(description = "Entity was last modified by (User, AMQP-Controller, anonymous etc.)", + accessMode = Schema.AccessMode.READ_ONLY, example = "bumlux") private String lastModifiedBy; - @JsonProperty - @Schema(example = "1691065906407") + + @JsonProperty(access = JsonProperty.Access.READ_ONLY) + @Schema(description = "Entity was last modified at (timestamp UTC in milliseconds)", + accessMode = Schema.AccessMode.READ_ONLY, example = "1691065906407") private Long lastModifiedAt; /** @@ -47,34 +54,4 @@ public abstract class MgmtBaseEntity extends RepresentationModel public Link getId() { return this.getRequiredLink("self"); } - - @JsonIgnore - public void setCreatedBy(final String createdBy) { - this.createdBy = createdBy; - } - - /** - * @param createdAt the createdAt to set - */ - @JsonIgnore - public void setCreatedAt(final Long createdAt) { - this.createdAt = createdAt; - } - - /** - * @param lastModifiedBy the lastModifiedBy to set - */ - @JsonIgnore - public void setLastModifiedBy(final String lastModifiedBy) { - this.lastModifiedBy = lastModifiedBy; - } - - /** - * @param lastModifiedAt - * the lastModifiedAt to set - */ - @JsonIgnore - public void setLastModifiedAt(final Long lastModifiedAt) { - this.lastModifiedAt = lastModifiedAt; - } } \ No newline at end of file diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/action/MgmtAction.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/action/MgmtAction.java index b15776fd5..0ae6938f5 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/action/MgmtAction.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/action/MgmtAction.java @@ -28,6 +28,40 @@ import com.fasterxml.jackson.annotation.JsonProperty; @EqualsAndHashCode(callSuper = true) @JsonInclude(Include.NON_NULL) @JsonIgnoreProperties(ignoreUnknown = true) +@Schema(example = """ + { + "createdBy" : "bumlux", + "createdAt" : 1682408571231, + "lastModifiedBy" : "bumlux", + "lastModifiedAt" : 1682408571265, + "type" : "update", + "status" : "finished", + "detailStatus" : "finished", + "rollout" : 1, + "rolloutName" : "rollout", + "_links" : { + "self" : { + "href" : "https://management-api.host.com/rest/v1/targets/target137/actions/1" + }, + "target" : { + "href" : "https://management-api.host.com/rest/v1/targets/target137", + "name" : "target137" + }, + "distributionset" : { + "href" : "https://management-api.host.com/rest/v1/distributionsets/1", + "name" : "DS:1.0" + }, + "status" : { + "href" : "https://management-api.host.com/rest/v1/targets/target137/actions/1/status?offset=0&limit=50&sort=id%3ADESC" + }, + "rollout" : { + "href" : "https://management-api.host.com/rest/v1/rollouts/1", + "name" : "rollout" + } + }, + "id" : 1, + "forceType" : "forced" + }""") public class MgmtAction extends MgmtBaseEntity { /** @@ -48,16 +82,16 @@ public class MgmtAction extends MgmtBaseEntity { public static final String ACTION_PENDING = "pending"; @JsonProperty("id") - @Schema(example = "7") + @Schema(description = "ID of the action", example = "7") private Long actionId; @JsonProperty - @Schema(example = "update") + @Schema(description = "Type of action", example = "update") private String type; @JsonProperty - @Schema(example = "finished") + @Schema(description = "Status of action", example = "finished") private String status; @JsonProperty - @Schema(example = "finished") + @Schema(description = "Detailed status of action", example = "finished") private String detailStatus; @JsonProperty @Schema(example = "1691065903238") @@ -65,18 +99,19 @@ public class MgmtAction extends MgmtBaseEntity { @JsonProperty(value = "forceType") private MgmtActionType actionType; @JsonProperty - @Schema(example = "600") + @Schema(description = "Weight of the action showing the importance of the update", example = "600") private Integer weight; @JsonProperty @Schema(hidden = true) private MgmtMaintenanceWindow maintenanceWindow; @JsonProperty - @Schema(example = "1") + @Schema(description = "The ID of the rollout this action was created for", example = "1") private Long rollout; @JsonProperty - @Schema(example = "rollout") + @Schema(description = "The name of the rollout this action was created for", example = "rollout") private String rolloutName; @JsonProperty - @Schema(example = "200") + @Schema(description = "(Optional) Code provided as part of the last status update that was sent by the device.", + example = "200") private Integer lastStatusCode; } \ No newline at end of file diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtActionRestApi.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtActionRestApi.java index 702a25d63..10afc02dc 100644 --- a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtActionRestApi.java +++ b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtActionRestApi.java @@ -54,46 +54,82 @@ public interface MgmtActionRestApi { * status OK. The response is always paged. In any failure the * JsonResponseExceptionHandler is handling the response. */ - @Operation(summary = "Return all actions", description = "Handles the GET request of retrieving all actions.") @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.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), - @ApiResponse(responseCode = "403", 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 = "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.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), - @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))) + @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.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), + @ApiResponse(responseCode = "403", 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 = "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.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), + @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts " + + "and the client has to wait another second.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))) }) @GetMapping(value = MgmtRestConstants.ACTION_V1_REQUEST_MAPPING, produces = { MediaTypes.HAL_JSON_VALUE, MediaType.APPLICATION_JSON_VALUE }) ResponseEntity> getActions( - @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_OFFSET, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_OFFSET) int pagingOffsetParam, - @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_PAGING_LIMIT, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_PAGING_DEFAULT_LIMIT) int pagingLimitParam, - @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SORTING, required = false) String sortParam, - @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_SEARCH, required = false) String rsqlParam, - @RequestParam(value = MgmtRestConstants.REQUEST_PARAMETER_REPRESENTATION_MODE, defaultValue = MgmtRestConstants.REQUEST_PARAMETER_REPRESENTATION_MODE_DEFAULT) String representationModeParam); + @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) + @Schema(description = """ + The representation mode. Can be "full" or "compact". Defaults to "compact" + """) + String representationModeParam); /** * Handles the GET request of retrieving a specific {@link MgmtAction} by * its actionId. * - * @param actionId - * The ID of the requested action + * @param actionId The ID of the requested action * * @return the {@link MgmtAction} */ - @Operation(summary = "Return action by id", description = "Handles the GET request of retrieving a single action by actionId.") + @Operation(summary = "Return action by id", + description = "Handles the GET request of retrieving a single action by actionId.") @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.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), - @ApiResponse(responseCode = "404", description = "Target not found.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), - @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), - @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts and the client has to wait another second.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))) + @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.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), + @ApiResponse(responseCode = "404", description = "Target not found.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), + @ApiResponse(responseCode = "406", description = "In case accept header is specified and not application/json.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))), + @ApiResponse(responseCode = "429", description = "Too many requests. The server will refuse further attempts" + + " and the client has to wait another second.", + content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))) }) @GetMapping(value = MgmtRestConstants.ACTION_V1_REQUEST_MAPPING + "/{actionId}", produces = { MediaTypes.HAL_JSON_VALUE, MediaType.APPLICATION_JSON_VALUE }) ResponseEntity getAction(@PathVariable("actionId") Long actionId); - } \ No newline at end of file