JAMES-2272 Docs: Add swagger documentation to TaskRoutes
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/54b79056 Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/54b79056 Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/54b79056 Branch: refs/heads/master Commit: 54b790562692ced5a0fbfb420108caabc75035bd Parents: 1561b6a Author: benwa <[email protected]> Authored: Wed Dec 27 16:04:20 2017 +0700 Committer: benwa <[email protected]> Committed: Thu Jan 4 15:12:47 2018 +0700 ---------------------------------------------------------------------- .../routes/CassandraMigrationRoutes.java | 161 +++++++++++++------ .../james/webadmin/routes/TasksRoutes.java | 62 ++++++- 2 files changed, 170 insertions(+), 53 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/54b79056/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java ---------------------------------------------------------------------- diff --git a/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java b/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java index bff6d1f..4ae87ed 100644 --- a/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java +++ b/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java @@ -20,6 +20,10 @@ package org.apache.james.webadmin.routes; import javax.inject.Inject; +import javax.ws.rs.GET; +import javax.ws.rs.POST; +import javax.ws.rs.Path; +import javax.ws.rs.Produces; import org.apache.james.backends.cassandra.migration.CassandraMigrationService; import org.apache.james.backends.cassandra.migration.Migration; @@ -36,8 +40,20 @@ import org.eclipse.jetty.http.HttpStatus; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.ResponseHeader; +import spark.Request; +import spark.Response; import spark.Service; +@Api(tags = "Cassandra migration") +@Path(":cassandra/version") +@Produces("application/json") public class CassandraMigrationRoutes implements Routes { private static final Logger LOGGER = LoggerFactory.getLogger(CassandraMigrationRoutes.class); @@ -65,54 +81,101 @@ public class CassandraMigrationRoutes implements Routes { @Override public void define(Service service) { - service.get(VERSION_BASE, - (request, response) -> new CassandraVersionResponse(cassandraMigrationService.getCurrentVersion()), - jsonTransformer); - - service.get(VERSION_BASE_LATEST, - (request, response) -> new CassandraVersionResponse(cassandraMigrationService.getLatestVersion()), - jsonTransformer); - - service.post(VERSION_UPGRADE_BASE, (request, response) -> { - LOGGER.debug("Cassandra upgrade launched"); - try { - CassandraVersionRequest cassandraVersionRequest = CassandraVersionRequest.parse(request.body()); - Migration migration = cassandraMigrationService.upgradeToVersion(cassandraVersionRequest.getValue()); - TaskId taskId = taskManager.submit(migration); - return TaskIdDto.respond(response, taskId); - } catch (NullPointerException | IllegalArgumentException e) { - LOGGER.info(INVALID_VERSION_UPGRADE_REQUEST); - throw ErrorResponder.builder() - .statusCode(HttpStatus.BAD_REQUEST_400) - .type(ErrorType.INVALID_ARGUMENT) - .message(INVALID_VERSION_UPGRADE_REQUEST) - .cause(e) - .haltError(); - } catch (IllegalStateException e) { - LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e); - throw ErrorResponder.builder() - .statusCode(HttpStatus.CONFLICT_409) - .type(ErrorType.WRONG_STATE) - .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE) - .cause(e) - .haltError(); - } - }, jsonTransformer); - - service.post(VERSION_UPGRADE_TO_LATEST_BASE, (request, response) -> { - try { - Migration migration = cassandraMigrationService.upgradeToLastVersion(); - TaskId taskId = taskManager.submit(migration); - return TaskIdDto.respond(response, taskId); - } catch (IllegalStateException e) { - LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e); - throw ErrorResponder.builder() - .statusCode(HttpStatus.CONFLICT_409) - .type(ErrorType.WRONG_STATE) - .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE) - .cause(e) - .haltError(); - } - }, jsonTransformer); + service.get(VERSION_BASE, (request, response) -> getCassandraCurrentVersion(), jsonTransformer); + + service.get(VERSION_BASE_LATEST, (request, response) -> getCassandraLatestVersion(), jsonTransformer); + + service.post(VERSION_UPGRADE_BASE, this::upgradeToVersion, jsonTransformer); + + service.post(VERSION_UPGRADE_TO_LATEST_BASE, (request, response) -> upgradeToLatest(response), jsonTransformer); + } + + @POST + @Path("upgrade/latest") + @ApiOperation("Triggers a migration of Cassandra schema to the latest available") + @ApiResponses({ + @ApiResponse(code = HttpStatus.CREATED_201, message = "The taskId of the given scheduled task", response = TaskIdDto.class, + responseHeaders = { + @ResponseHeader(name = "Location", description = "URL of the resource associated with the scheduled task") + }), + @ApiResponse(code = HttpStatus.CONFLICT_409, message = "Migration can not be done") + }) + public Object upgradeToLatest(Response response) { + try { + Migration migration = cassandraMigrationService.upgradeToLastVersion(); + TaskId taskId = taskManager.submit(migration); + return TaskIdDto.respond(response, taskId); + } catch (IllegalStateException e) { + LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e); + throw ErrorResponder.builder() + .statusCode(HttpStatus.CONFLICT_409) + .type(ErrorType.WRONG_STATE) + .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE) + .cause(e) + .haltError(); + } + } + + @POST + @Path("upgrade") + @ApiOperation("Triggers a migration of Cassandra schema to a specific version") + @ApiImplicitParams({ + @ApiImplicitParam( + required = true, + paramType = "body", + dataType = "Integer", + example = "3", + value = "The schema version to upgrade to.") + }) + @ApiResponses({ + @ApiResponse(code = HttpStatus.CREATED_201, message = "The taskId of the given scheduled task", response = TaskIdDto.class, + responseHeaders = { + @ResponseHeader(name = "Location", description = "URL of the resource associated with the scheduled task") + }), + @ApiResponse(code = HttpStatus.CONFLICT_409, message = "Migration can not be done") + }) + public Object upgradeToVersion(Request request, Response response) { + LOGGER.debug("Cassandra upgrade launched"); + try { + CassandraVersionRequest cassandraVersionRequest = CassandraVersionRequest.parse(request.body()); + Migration migration = cassandraMigrationService.upgradeToVersion(cassandraVersionRequest.getValue()); + TaskId taskId = taskManager.submit(migration); + return TaskIdDto.from(taskId); + } catch (NullPointerException | IllegalArgumentException e) { + LOGGER.info(INVALID_VERSION_UPGRADE_REQUEST); + throw ErrorResponder.builder() + .statusCode(HttpStatus.BAD_REQUEST_400) + .type(ErrorType.INVALID_ARGUMENT) + .message(INVALID_VERSION_UPGRADE_REQUEST) + .cause(e) + .haltError(); + } catch (IllegalStateException e) { + LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e); + throw ErrorResponder.builder() + .statusCode(HttpStatus.CONFLICT_409) + .type(ErrorType.WRONG_STATE) + .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE) + .cause(e) + .haltError(); + } + } + + @GET + @Path("latest") + @ApiOperation(value = "Getting the latest version available for Cassandra schema") + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.OK_200, message = "The latest version of the schema", response = CassandraVersionResponse.class) + }) + public CassandraVersionResponse getCassandraLatestVersion() { + return new CassandraVersionResponse(cassandraMigrationService.getLatestVersion()); + } + + @GET + @ApiOperation(value = "Getting the current version used by Cassandra schema") + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.OK_200, message = "The current version of the schema", response = CassandraVersionResponse.class) + }) + public CassandraVersionResponse getCassandraCurrentVersion() { + return new CassandraVersionResponse(cassandraMigrationService.getCurrentVersion()); } } http://git-wip-us.apache.org/repos/asf/james-project/blob/54b79056/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java ---------------------------------------------------------------------- diff --git a/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java b/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java index 99bd2df..9116b51 100644 --- a/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java +++ b/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java @@ -19,11 +19,16 @@ package org.apache.james.webadmin.routes; +import java.util.List; import java.util.Optional; import java.util.UUID; import java.util.function.Supplier; import javax.inject.Inject; +import javax.ws.rs.DELETE; +import javax.ws.rs.GET; +import javax.ws.rs.Path; +import javax.ws.rs.Produces; import org.apache.james.task.TaskExecutionDetails; import org.apache.james.task.TaskId; @@ -36,10 +41,19 @@ import org.apache.james.webadmin.utils.ErrorResponder; import org.apache.james.webadmin.utils.JsonTransformer; import org.eclipse.jetty.http.HttpStatus; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import spark.Request; import spark.Response; import spark.Service; +@Api(tags = "Tasks") +@Path(":task") +@Produces("application/json") public class TasksRoutes implements Routes { public static final String BASE = "/tasks"; private final TaskManager taskManager; @@ -62,7 +76,24 @@ public class TasksRoutes implements Routes { service.get(BASE, this::list, jsonTransformer); } - private Object list(Request req, Response response) { + @GET + @ApiOperation(value = "Listing tasks") + @ApiImplicitParams({ + @ApiImplicitParam( + required = false, + paramType = "query parameter", + dataType = "String", + defaultValue = "None", + example = "?status=inProgress", + value = "If present, allow to filter the tasks and keep only the one with a given status. " + + "The status are one of [waiting, inProgress, failed, canceled, completed]") + }) + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = List.class), + @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The provided payload is invalid (JSON error or invalid status)"), + @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found") + }) + public Object list(Request req, Response response) { try { return ExecutionDetailsDto.from( Optional.ofNullable(req.queryParams("status")) @@ -79,13 +110,29 @@ public class TasksRoutes implements Routes { } } - private Object getStatus(Request req, Response response) { + @GET + @Path("/{taskId}") + @ApiOperation(value = "Getting a task execution details") + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = ExecutionDetailsDto.class), + @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid"), + @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found") + }) + public Object getStatus(Request req, Response response) { TaskId taskId = getTaskId(req); return respondStatus(taskId, () -> taskManager.getExecutionDetails(getTaskId(req))); } - private Object await(Request req, Response response) { + @GET + @Path("/{taskId}/await") + @ApiOperation(value = "Await, then get a task execution details") + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = ExecutionDetailsDto.class), + @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid"), + @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found") + }) + public Object await(Request req, Response response) { TaskId taskId = getTaskId(req); return respondStatus(taskId, () -> taskManager.await(getTaskId(req))); @@ -104,7 +151,14 @@ public class TasksRoutes implements Routes { } } - private Object cancel(Request req, Response response) { + @DELETE + @Path("/{taskId}") + @ApiOperation(value = "Cancel a given task") + @ApiResponses(value = { + @ApiResponse(code = HttpStatus.NO_CONTENT_204, message = "Task is cancelled"), + @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid") + }) + public Object cancel(Request req, Response response) { TaskId taskId = getTaskId(req); taskManager.cancel(taskId); response.status(HttpStatus.NO_CONTENT_204); --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
