JAMES-2099 Swagger API for UserMaibox and GlobalQuota
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/9cd602f1 Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/9cd602f1 Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/9cd602f1 Branch: refs/heads/master Commit: 9cd602f10506932f550169852be0bd27b0799db7 Parents: 80dae30 Author: quynhn <qngu...@linagora.com> Authored: Tue Jul 25 18:02:47 2017 +0700 Committer: quynhn <qngu...@linagora.com> Committed: Mon Jul 31 10:56:17 2017 +0700 ---------------------------------------------------------------------- .../webadmin/routes/GlobalQuotaRoutes.java | 181 +++++++++++++++---- .../webadmin/routes/UserMailboxesRoutes.java | 133 ++++++++++++-- 2 files changed, 264 insertions(+), 50 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/9cd602f1/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/GlobalQuotaRoutes.java ---------------------------------------------------------------------- diff --git a/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/GlobalQuotaRoutes.java b/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/GlobalQuotaRoutes.java index eeca83a..d53608a 100644 --- a/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/GlobalQuotaRoutes.java +++ b/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/GlobalQuotaRoutes.java @@ -20,6 +20,11 @@ package org.apache.james.webadmin.routes; import javax.inject.Inject; +import javax.ws.rs.DELETE; +import javax.ws.rs.GET; +import javax.ws.rs.PUT; +import javax.ws.rs.Path; +import javax.ws.rs.Produces; import org.apache.james.mailbox.model.Quota; import org.apache.james.mailbox.quota.MaxQuotaManager; @@ -30,11 +35,20 @@ import org.apache.james.webadmin.dto.QuotaRequest; import org.apache.james.webadmin.utils.JsonExtractException; import org.apache.james.webadmin.utils.JsonExtractor; import org.apache.james.webadmin.utils.JsonTransformer; + +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 org.slf4j.Logger; import org.slf4j.LoggerFactory; - import spark.Service; +@Api(tags = "GlobalQuota") +@Path(GlobalQuotaRoutes.QUOTA_ENDPOINT) +@Produces("application/json") public class GlobalQuotaRoutes implements Routes { public static final String QUOTA_ENDPOINT = "/quota"; @@ -45,6 +59,7 @@ public class GlobalQuotaRoutes implements Routes { private final MaxQuotaManager maxQuotaManager; private final JsonTransformer jsonTransformer; private final JsonExtractor<QuotaDTO> jsonExtractor; + private Service service; @Inject public GlobalQuotaRoutes(MaxQuotaManager maxQuotaManager, JsonTransformer jsonTransformer) { @@ -55,42 +70,96 @@ public class GlobalQuotaRoutes implements Routes { @Override public void define(Service service) { - service.get(COUNT_ENDPOINT, (request, response) -> { - long value = maxQuotaManager.getDefaultMaxMessage(); - response.status(200); - return value; - }, jsonTransformer); + this.service = service; - service.delete(COUNT_ENDPOINT, (request, response) -> { - maxQuotaManager.setDefaultMaxMessage(Quota.UNLIMITED); - response.status(204); - return Constants.EMPTY_BODY; - }); + defineGetQuotaCount(); - service.put(COUNT_ENDPOINT, (request, response) -> { + defineDeleteQuotaCount(); + + defineUpdateQuotaCount(); + + defineGetQuotaSize(); + + defineDeleteQuotaSize(); + + defineUpdateQuotaSize(); + + defineGetQuota(); + + defineUpdateQuota(); + } + + @PUT + @ApiOperation(value = "Updating count and size at the same time") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "org.apache.james.webadmin.dto.QuotaDTO", paramType = "body") + }) + @ApiResponses(value = { + @ApiResponse(code = 204, message = "OK. The value has been updated."), + @ApiResponse(code = 400, message = "The body is not a positive integer or not unlimited value (-1)."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineUpdateQuota() { + service.put(QUOTA_ENDPOINT, ((request, response) -> { try { - QuotaRequest quotaRequest = QuotaRequest.parse(request.body()); - maxQuotaManager.setDefaultMaxMessage(quotaRequest.getValue()); + QuotaDTO quotaDTO = jsonExtractor.parse(request.body()); + maxQuotaManager.setDefaultMaxMessage(quotaDTO.getCount()); + maxQuotaManager.setDefaultMaxStorage(quotaDTO.getSize()); response.status(204); + } catch (JsonExtractException e) { + LOGGER.info("Malformed JSON", e); + response.status(400); } catch (IllegalArgumentException e) { - LOGGER.info("Invalid quota. Need to be an integer value greater than 0"); + LOGGER.info("Quota should be positive or unlimited (-1)", e); response.status(400); } return Constants.EMPTY_BODY; - }); + })); + } - service.get(SIZE_ENDPOINT, (request, response) -> { - long value = maxQuotaManager.getDefaultMaxStorage(); + @GET + @ApiOperation(value = "Reading count and size at the same time") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK", response = QuotaDTO.class), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineGetQuota() { + service.get(QUOTA_ENDPOINT, (request, response) -> { + QuotaDTO quotaDTO = QuotaDTO.builder() + .count(maxQuotaManager.getDefaultMaxMessage()) + .size(maxQuotaManager.getDefaultMaxStorage()).build(); response.status(200); - return value; + return quotaDTO; }, jsonTransformer); + } + @DELETE + @Path("/size") + @ApiOperation(value = "Removing per quotaroot mail size limitation by updating to unlimited value") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The value is updated to unlimited value."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineDeleteQuotaSize() { service.delete(SIZE_ENDPOINT, (request, response) -> { maxQuotaManager.setDefaultMaxStorage(Quota.UNLIMITED); response.status(204); return Constants.EMPTY_BODY; }); + } + @PUT + @Path("/size") + @ApiOperation(value = "Updating per quotaroot mail size limitation") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "integer", paramType = "body") + }) + @ApiResponses(value = { + @ApiResponse(code = 204, message = "OK. The value has been updated."), + @ApiResponse(code = 400, message = "The body is not a positive integer."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineUpdateQuotaSize() { service.put(SIZE_ENDPOINT, (request, response) -> { try { QuotaRequest quotaRequest = QuotaRequest.parse(request.body()); @@ -102,29 +171,75 @@ public class GlobalQuotaRoutes implements Routes { } return Constants.EMPTY_BODY; }); + } - service.get(QUOTA_ENDPOINT, (request, response) -> { - QuotaDTO quotaDTO = QuotaDTO.builder() - .count(maxQuotaManager.getDefaultMaxMessage()) - .size(maxQuotaManager.getDefaultMaxStorage()).build(); + @GET + @Path("/size") + @ApiOperation(value = "Reading per quotaroot mail size limitation") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK", response = Long.class), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineGetQuotaSize() { + service.get(SIZE_ENDPOINT, (request, response) -> { + long value = maxQuotaManager.getDefaultMaxStorage(); response.status(200); - return quotaDTO; + return value; }, jsonTransformer); + } - service.put(QUOTA_ENDPOINT, ((request, response) -> { + @DELETE + @Path("/count") + @ApiOperation(value = "Removing per quotaroot mail count limitation by updating to unlimited value") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The value is updated to unlimited value."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineDeleteQuotaCount() { + service.delete(COUNT_ENDPOINT, (request, response) -> { + maxQuotaManager.setDefaultMaxMessage(Quota.UNLIMITED); + response.status(204); + return Constants.EMPTY_BODY; + }); + } + + @PUT + @Path("/count") + @ApiOperation(value = "Updating per quotaroot mail count limitation") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "integer", paramType = "body") + }) + @ApiResponses(value = { + @ApiResponse(code = 204, message = "OK. The value has been updated."), + @ApiResponse(code = 400, message = "The body is not a positive integer."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineUpdateQuotaCount() { + service.put(COUNT_ENDPOINT, (request, response) -> { try { - QuotaDTO quotaDTO = jsonExtractor.parse(request.body()); - maxQuotaManager.setDefaultMaxMessage(quotaDTO.getCount()); - maxQuotaManager.setDefaultMaxStorage(quotaDTO.getSize()); + QuotaRequest quotaRequest = QuotaRequest.parse(request.body()); + maxQuotaManager.setDefaultMaxMessage(quotaRequest.getValue()); response.status(204); - } catch (JsonExtractException e) { - LOGGER.info("Malformed JSON", e); - response.status(400); } catch (IllegalArgumentException e) { - LOGGER.info("Quota should be positive or unlimited (-1)", e); + LOGGER.info("Invalid quota. Need to be an integer value greater than 0"); response.status(400); } return Constants.EMPTY_BODY; - })); + }); + } + + @GET + @Path("/count") + @ApiOperation(value = "Reading per quotaroot mail count limitation") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK", response = Long.class), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineGetQuotaCount() { + service.get(COUNT_ENDPOINT, (request, response) -> { + long value = maxQuotaManager.getDefaultMaxMessage(); + response.status(200); + return value; + }, jsonTransformer); } } http://git-wip-us.apache.org/repos/asf/james-project/blob/9cd602f1/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/UserMailboxesRoutes.java ---------------------------------------------------------------------- diff --git a/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/UserMailboxesRoutes.java b/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/UserMailboxesRoutes.java index 79a6915..1b218f5 100644 --- a/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/UserMailboxesRoutes.java +++ b/server/protocols/webadmin/webadmin-mailbox/src/main/java/org/apache/james/webadmin/routes/UserMailboxesRoutes.java @@ -20,6 +20,11 @@ package org.apache.james.webadmin.routes; import javax.inject.Inject; +import javax.ws.rs.DELETE; +import javax.ws.rs.GET; +import javax.ws.rs.PUT; +import javax.ws.rs.Path; +import javax.ws.rs.Produces; import org.apache.james.webadmin.Constants; import org.apache.james.webadmin.Routes; @@ -27,11 +32,20 @@ import org.apache.james.webadmin.service.UserMailboxesService; import org.apache.james.webadmin.utils.JsonTransformer; import org.apache.james.webadmin.utils.MailboxHaveChildrenException; import org.apache.james.webadmin.validation.MailboxName; + +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 org.slf4j.Logger; import org.slf4j.LoggerFactory; - import spark.Service; +@Api(tags = "User's Mailbox") +@Path("/users/{username}/mailboxes") +@Produces("application/json") public class UserMailboxesRoutes implements Routes { private static final Logger LOGGER = LoggerFactory.getLogger(UserMailboxesRoutes.class); @@ -45,6 +59,7 @@ public class UserMailboxesRoutes implements Routes { private final UserMailboxesService userMailboxesService; private final JsonTransformer jsonTransformer; + private Service service; @Inject public UserMailboxesRoutes(UserMailboxesService userMailboxesService, JsonTransformer jsonTransformer) { @@ -54,21 +69,58 @@ public class UserMailboxesRoutes implements Routes { @Override public void define(Service service) { + this.service = service; - service.put(SPECIFIC_MAILBOX, (request, response) -> { + defineMailboxExists(); + + defineGetUserMailboxes(); + + defineCreateUserMailbox(); + + defineDeleteUserMailbox(); + + defineDeleteUserMailboxes(); + } + + @GET + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "string", name = "username", paramType = "path") + }) + @ApiOperation(value = "Listing all mailboxes of user.") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The list of mailboxes", response = String.class), + @ApiResponse(code = 401, message = "Unauthorized. The user is not authenticated on the platform", response = String.class), + @ApiResponse(code = 404, message = "The user name does not exist."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineGetUserMailboxes() { + service.get(USER_MAILBOXES_BASE, (request, response) -> { + response.status(200); try { - userMailboxesService.createMailbox(request.params(USER_NAME), new MailboxName(request.params(MAILBOX_NAME))); - response.status(204); + return userMailboxesService.listMailboxes(request.params(USER_NAME)); } catch (IllegalStateException e) { - LOGGER.info("Invalid put on user mailbox", e); + LOGGER.info("Invalid get on user mailboxes", e); response.status(404); - } catch (IllegalArgumentException e) { - LOGGER.info("Attempt to create an invalid mailbox"); - response.status(400); + return Constants.EMPTY_BODY; } - return Constants.EMPTY_BODY; - }); + }, jsonTransformer); + } + @DELETE + @Path("/{mailboxName}") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "string", name = "username", paramType = "path"), + @ApiImplicitParam(required = true, dataType = "string", name = "mailboxName", paramType = "path") + }) + @ApiOperation(value = "Deleting a mailbox and its children") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The mailbox now does not exist on the server", response = String.class), + @ApiResponse(code = 400, message = "Invalid mailbox name"), + @ApiResponse(code = 401, message = "Unauthorized. The user is not authenticated on the platform"), + @ApiResponse(code = 404, message = "The user name does not exist."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineDeleteUserMailbox() { service.delete(SPECIFIC_MAILBOX, (request, response) -> { try { userMailboxesService.deleteMailbox(request.params(USER_NAME), new MailboxName(request.params(MAILBOX_NAME))); @@ -85,7 +137,20 @@ public class UserMailboxesRoutes implements Routes { } return Constants.EMPTY_BODY; }); + } + @DELETE + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "string", name = "username", paramType = "path") + }) + @ApiOperation(value = "Deleting user mailboxes.") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The user does not have any mailbox", response = String.class), + @ApiResponse(code = 401, message = "Unauthorized. The user is not authenticated on the platform"), + @ApiResponse(code = 404, message = "The user name does not exist."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineDeleteUserMailboxes() { service.delete(USER_MAILBOXES_BASE, (request, response) -> { try { userMailboxesService.deleteMailboxes(request.params(USER_NAME)); @@ -96,7 +161,23 @@ public class UserMailboxesRoutes implements Routes { } return Constants.EMPTY_BODY; }); + } + @GET + @Path("/{mailboxName}") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "string", name = "username", paramType = "path"), + @ApiImplicitParam(required = true, dataType = "string", name = "mailboxName", paramType = "path") + }) + @ApiOperation(value = "Testing existence of a mailbox.") + @ApiResponses(value = { + @ApiResponse(code = 204, message = "The mailbox exists", response = String.class), + @ApiResponse(code = 400, message = "Invalid mailbox name"), + @ApiResponse(code = 401, message = "Unauthorized. The user is not authenticated on the platform"), + @ApiResponse(code = 404, message = "The user name does not exist."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineMailboxExists() { service.get(SPECIFIC_MAILBOX, (request, response) -> { try { if (userMailboxesService.testMailboxExists(request.params(USER_NAME), new MailboxName(request.params(MAILBOX_NAME)))) { @@ -113,17 +194,35 @@ public class UserMailboxesRoutes implements Routes { } return Constants.EMPTY_BODY; }); + } - service.get(USER_MAILBOXES_BASE, (request, response) -> { - response.status(200); + @PUT + @Path("/{mailboxName}") + @ApiOperation(value = "Create a mailbox of the selected user.", nickname = "CreateUserMailbox") + @ApiImplicitParams({ + @ApiImplicitParam(required = true, dataType = "string", name = "username", paramType = "path"), + @ApiImplicitParam(required = true, dataType = "string", name = "mailboxName", paramType = "path") + }) + @ApiResponses(value = { + @ApiResponse(code = 204, message = "OK. The mailbox now exists on the server.", response = String.class), + @ApiResponse(code = 400, message = "Invalid mailbox name"), + @ApiResponse(code = 401, message = "Unauthorized. The user is not authenticated on the platform"), + @ApiResponse(code = 404, message = "The user name does not exist."), + @ApiResponse(code = 500, message = "Internal server error - Something went bad on the server side.") + }) + public void defineCreateUserMailbox() { + service.put(SPECIFIC_MAILBOX, (request, response) -> { try { - return userMailboxesService.listMailboxes(request.params(USER_NAME)); + userMailboxesService.createMailbox(request.params(USER_NAME), new MailboxName(request.params(MAILBOX_NAME))); + response.status(204); } catch (IllegalStateException e) { - LOGGER.info("Invalid get on user mailboxes", e); + LOGGER.info("Invalid put on user mailbox", e); response.status(404); - return Constants.EMPTY_BODY; + } catch (IllegalArgumentException e) { + LOGGER.info("Attempt to create an invalid mailbox"); + response.status(400); } - }, jsonTransformer); - + return Constants.EMPTY_BODY; + }); } } --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
