james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From btell...@apache.org
Subject [18/21] james-project git commit: JAMES-2272 Docs: Add swagger documentation to TaskRoutes
Date Thu, 04 Jan 2018 08:13:33 GMT
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 <btellier@linagora.com>
Authored: Wed Dec 27 16:04:20 2017 +0700
Committer: benwa <btellier@linagora.com>
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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message