Skip to content

Commit

Permalink
REST doc / Mgmt Actions - fix missed info (#1619)
Browse files Browse the repository at this point in the history 
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 <Avgustin.Marinov@bosch.com>
  • Loading branch information
@avgustinmm
avgustinmm committed Feb 7, 2024
1 parent fc561c3 commit 3808d86
Show file tree
Hide file tree
Showing 3 changed files with 115 additions and 67 deletions.
53 changes: 15 additions & 38 deletions ...st/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java
View file
Expand Up @@ -25,17 +25,24 @@
@EqualsAndHashCode(callSuper = true)
public abstract class MgmtBaseEntity extends RepresentationModel<MgmtBaseEntity> {

@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;

/**
Expand All @@ -47,34 +54,4 @@ public abstract class MgmtBaseEntity extends RepresentationModel<MgmtBaseEntity>
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;
}
}
51 changes: 43 additions & 8 deletions ...hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/action/MgmtAction.java
View file
Expand Up @@ -28,6 +28,40 @@
@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 {

/**
Expand All @@ -48,35 +82,36 @@ 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")
private Long forceTime;
@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;
}
78 changes: 57 additions & 21 deletions ...t/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/rest/api/MgmtActionRestApi.java
View file
Expand Up @@ -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<PagedList<MgmtAction>> 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 <code>actionId</code>.
*
* @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<MgmtAction> getAction(@PathVariable("actionId") Long actionId);

}

0 comments on commit 3808d86

Please sign in to comment.