From 423879bee7b9695cf9d5169dbca8f362e26351bb Mon Sep 17 00:00:00 2001 From: charitha Date: Mon, 30 Jan 2017 20:41:05 +0530 Subject: [PATCH] Updated swagger docs --- .../service/api/DeviceManagementService.java | 91 +++++++++++++++++-- .../service/api/GroupManagementService.java | 69 +++++++------- .../admin/GroupManagementAdminService.java | 22 +++-- .../impl/DeviceManagementServiceImpl.java | 1 + .../impl/GroupManagementServiceImpl.java | 30 +++--- .../GroupManagementAdminServiceImpl.java | 10 +- 6 files changed, 153 insertions(+), 70 deletions(-) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java index 6bf11f4ac4..b655b7b26b 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java @@ -18,32 +18,40 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.SwaggerDefinition; -import io.swagger.annotations.Info; -import io.swagger.annotations.ExtensionProperty; -import io.swagger.annotations.Extension; -import io.swagger.annotations.Tag; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.Extension; +import io.swagger.annotations.ExtensionProperty; +import io.swagger.annotations.Info; import io.swagger.annotations.ResponseHeader; +import io.swagger.annotations.SwaggerDefinition; +import io.swagger.annotations.Tag; import org.wso2.carbon.apimgt.annotations.api.Scope; import org.wso2.carbon.apimgt.annotations.api.Scopes; import org.wso2.carbon.device.mgt.common.Device; import org.wso2.carbon.device.mgt.common.Feature; import org.wso2.carbon.device.mgt.common.app.mgt.Application; import org.wso2.carbon.device.mgt.common.operation.mgt.Operation; +import org.wso2.carbon.device.mgt.common.policy.mgt.Policy; +import org.wso2.carbon.device.mgt.common.policy.mgt.monitor.NonComplianceData; import org.wso2.carbon.device.mgt.common.search.SearchContext; import org.wso2.carbon.device.mgt.jaxrs.beans.DeviceList; import org.wso2.carbon.device.mgt.jaxrs.beans.ErrorResponse; import org.wso2.carbon.device.mgt.jaxrs.util.Constants; -import org.wso2.carbon.device.mgt.common.policy.mgt.Policy; -import org.wso2.carbon.device.mgt.common.policy.mgt.monitor.NonComplianceData; import javax.validation.constraints.Size; -import javax.ws.rs.*; +import javax.ws.rs.Consumes; +import javax.ws.rs.DELETE; +import javax.ws.rs.GET; +import javax.ws.rs.HeaderParam; +import javax.ws.rs.POST; +import javax.ws.rs.Path; +import javax.ws.rs.PathParam; +import javax.ws.rs.Produces; +import javax.ws.rs.QueryParam; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; @@ -141,7 +149,7 @@ public interface DeviceManagementService { produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Getting Details of Registered Devices", - notes = "Provides details of all the devices enrolled with WSO2 EMM.", + notes = "Provides details of all the devices enrolled with WSO2 IoT Server.", tags = "Device Management", extensions = { @Extension(properties = { @@ -266,6 +274,71 @@ public interface DeviceManagementService { @QueryParam("limit") int limit); + @GET + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Getting Details of Registered Devices owned by authenticated user", + notes = "Provides details of devices enrolled by authenticated user.", + tags = "Device Management", + extensions = { + @Extension(properties = { + @ExtensionProperty(name = Constants.SCOPE, value = "perm:devices:view") + }) + } + ) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK. \n Successfully fetched the list of devices.", + response = DeviceList.class, + responseHeaders = { + @ResponseHeader( + name = "Content-Type", + description = "The content type of the body"), + @ResponseHeader( + name = "ETag", + description = "Entity Tag of the response resource.\n" + + "Used by caches, or in conditional requests."), + @ResponseHeader( + name = "Last-Modified", + description = "Date and time the resource was last modified.\n" + + "Used by caches, or in conditional requests."), + }), + @ApiResponse( + code = 304, + message = "Not Modified. \n Empty body because the client already has the latest version of " + + "the requested resource.\n"), + @ApiResponse( + code = 400, + message = "The incoming request has more than one selection criteria defined via the query parameters.", + response = ErrorResponse.class), + @ApiResponse( + code = 404, + message = "The search criteria did not match any device registered with the server.", + response = ErrorResponse.class), + @ApiResponse( + code = 406, + message = "Not Acceptable.\n The requested media type is not supported."), + @ApiResponse( + code = 500, + message = "Internal Server Error. \n Server error occurred while fetching the device list.", + response = ErrorResponse.class) + }) + @Path("/user-devices") + Response getDeviceByUser( + @ApiParam( + name = "offset", + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") + @QueryParam("offset") + int offset, + @ApiParam( + name = "limit", + value = "Provide how many device details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") + @QueryParam("limit") + int limit); @GET @Path("/{type}/{id}") diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/GroupManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/GroupManagementService.java index 51a6dae87c..a815304fb0 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/GroupManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/GroupManagementService.java @@ -204,10 +204,6 @@ public interface GroupManagementService { code = 304, message = "Not Modified. \n Empty body because the client has already the latest version of " + "the requested resource."), - @ApiResponse( - code = 404, - message = "No groups found.", - response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported."), @@ -219,19 +215,25 @@ public interface GroupManagementService { Response getGroups(@ApiParam( name = "name", value = "Name of the group.") - @QueryParam("name") String name, + @QueryParam("name") + String name, @ApiParam( name = "owner", value = "Owner of the group.") - @QueryParam("owner") String owner, + @QueryParam("owner") + String owner, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.") - @QueryParam("offset") int offset, + value = "The starting pagination index for the complete list of qualified items.", + defaultValue = "0") + @QueryParam("offset") + int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.") - @QueryParam("limit") int limit); + value = "Provide how many device details you require from the starting pagination index/offset.", + defaultValue = "5") + @QueryParam("limit") + int limit); @Path("/count") @GET @@ -268,10 +270,6 @@ public interface GroupManagementService { code = 304, message = "Not Modified. \n Empty body because the client has already the latest version of " + "the requested resource."), - @ApiResponse( - code = 404, - message = "No groups found.", - response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported."), @@ -383,7 +381,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -435,7 +433,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group not found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -492,7 +490,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group not found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -544,7 +542,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group not found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -601,7 +599,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group not found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -653,7 +651,7 @@ public interface GroupManagementService { "the requested resource."), @ApiResponse( code = 404, - message = "No groups found.", + message = "Group not found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -667,15 +665,20 @@ public interface GroupManagementService { name = "groupId", value = "ID of the group.", required = true) - @PathParam("groupId") int groupId, + @PathParam("groupId") + int groupId, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.") - @QueryParam("offset") int offset, + value = "The starting pagination index for the complete list of qualified items.", + defaultValue = "0") + @QueryParam("offset") + int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.") - @QueryParam("limit") int limit); + value = "Provide how many device details you require from the starting pagination index/offset.", + defaultValue = "5") + @QueryParam("limit") + int limit); @Path("/id/{groupId}/devices/count") @GET @@ -926,10 +929,6 @@ public interface GroupManagementService { code = 304, message = "Not Modified. \n Empty body because the client has already the latest version of " + "the requested resource."), - @ApiResponse( - code = 404, - message = "No groups found.", - response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported."), @@ -941,11 +940,15 @@ public interface GroupManagementService { Response getGroups( @ApiParam( name = "deviceId", - value = "Id of the device.") - @QueryParam("deviceId") String deviceId, + value = "Id of the device.", + required = true) + @QueryParam("deviceId") + String deviceId, @ApiParam( name = "deviceType", - value = "Type of the device.") - @QueryParam("deviceType") String deviceType); + value = "Type of the device.", + required = true) + @QueryParam("deviceType") + String deviceType); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java index 64020ce56e..3e47728c3d 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java @@ -113,10 +113,6 @@ public interface GroupManagementAdminService { code = 304, message = "Not Modified. \n Empty body because the client has already the latest version of " + "the requested resource."), - @ApiResponse( - code = 404, - message = "No groups found.", - response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported."), @@ -128,19 +124,25 @@ public interface GroupManagementAdminService { Response getGroups(@ApiParam( name = "name", value = "Name of the group.") - @QueryParam("name") String name, + @QueryParam("name") + String name, @ApiParam( name = "owner", value = "Owner of the group.") - @QueryParam("owner") String owner, + @QueryParam("owner") + String owner, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.") - @QueryParam("offset") int offset, + value = "The starting pagination index for the complete list of qualified items.", + defaultValue = "0") + @QueryParam("offset") + int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.") - @QueryParam("limit") int limit); + value = "Provide how many device details you require from the starting pagination index/offset.", + defaultValue = "5") + @QueryParam("limit") + int limit); @Path("/count") @GET diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceManagementServiceImpl.java index bab0d1fd39..3532fbe38f 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceManagementServiceImpl.java @@ -221,6 +221,7 @@ public class DeviceManagementServiceImpl implements DeviceManagementService { } @GET + @Override @Path("/user-devices") public Response getDeviceByUser(@QueryParam("offset") int offset, @QueryParam("limit") int limit) { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/GroupManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/GroupManagementServiceImpl.java index 4811e9b902..cc5fa3ddac 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/GroupManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/GroupManagementServiceImpl.java @@ -65,14 +65,15 @@ public class GroupManagementServiceImpl implements GroupManagementService { request.setOwner(owner); PaginationResult deviceGroupsResult = DeviceMgtAPIUtils.getGroupManagementProviderService() .getGroups(currentUser, request); + DeviceGroupList deviceGroupList = new DeviceGroupList(); if (deviceGroupsResult.getData() != null && deviceGroupsResult.getRecordsTotal() > 0) { - DeviceGroupList deviceGroupList = new DeviceGroupList(); deviceGroupList.setList(deviceGroupsResult.getData()); deviceGroupList.setCount(deviceGroupsResult.getRecordsTotal()); - return Response.status(Response.Status.OK).entity(deviceGroupList).build(); } else { - return Response.status(Response.Status.NOT_FOUND).build(); + deviceGroupList.setList(new ArrayList<>()); + deviceGroupList.setCount(0); } + return Response.status(Response.Status.OK).entity(deviceGroupList).build(); } catch (GroupManagementException e) { String error = "Error occurred while getting the groups."; log.error(error, e); @@ -184,15 +185,15 @@ public class GroupManagementServiceImpl implements GroupManagementService { public Response getRolesOfGroup(int groupId) { try { List groupRoles = DeviceMgtAPIUtils.getGroupManagementProviderService().getRoles(groupId); - - if(groupRoles != null && groupRoles.size() > 0) { - RoleList deviceGroupRolesList = new RoleList(); + RoleList deviceGroupRolesList = new RoleList(); + if(groupRoles != null) { deviceGroupRolesList.setList(groupRoles); deviceGroupRolesList.setCount(groupRoles.size()); - return Response.status(Response.Status.OK).entity(deviceGroupRolesList).build(); } else { - return Response.status(Response.Status.OK).entity(EMPTY_RESULT).build(); + deviceGroupRolesList.setList(new ArrayList()); + deviceGroupRolesList.setCount(0); } + return Response.status(Response.Status.OK).entity(deviceGroupRolesList).build(); } catch (GroupManagementException e) { String msg = "Error occurred while getting roles of the group."; log.error(msg, e); @@ -205,14 +206,15 @@ public class GroupManagementServiceImpl implements GroupManagementService { try { GroupManagementProviderService service = DeviceMgtAPIUtils.getGroupManagementProviderService(); List deviceList = service.getDevices(groupId, offset, limit); - if (deviceList != null && deviceList.size() > 0) { - DeviceList deviceListWrapper = new DeviceList(); + int deviceCount = service.getDeviceCount(groupId); + DeviceList deviceListWrapper = new DeviceList(); + if (deviceList != null) { deviceListWrapper.setList(deviceList); - deviceListWrapper.setCount(service.getDeviceCount(groupId)); - return Response.status(Response.Status.OK).entity(deviceListWrapper).build(); } else { - return Response.status(Response.Status.NOT_FOUND).build(); + deviceListWrapper.setList(new ArrayList()); } + deviceListWrapper.setCount(deviceCount); + return Response.status(Response.Status.OK).entity(deviceListWrapper).build(); } catch (GroupManagementException e) { String msg = "Error occurred while getting devices the group."; log.error(msg, e); @@ -295,7 +297,7 @@ public class GroupManagementServiceImpl implements GroupManagementService { List deviceGroups = DeviceMgtAPIUtils.getGroupManagementProviderService().getGroups(deviceIdentifier); return Response.status(Response.Status.OK).entity(deviceGroups).build(); } catch (GroupManagementException e) { - String msg = "Error occurred while removing devices from group."; + String msg = "Error occurred while getting groups of device."; log.error(msg, e); return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(msg).build(); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/GroupManagementAdminServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/GroupManagementAdminServiceImpl.java index 55b67029fa..8222210cad 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/GroupManagementAdminServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/GroupManagementAdminServiceImpl.java @@ -32,6 +32,7 @@ import org.wso2.carbon.device.mgt.jaxrs.service.impl.util.RequestValidationUtil; import org.wso2.carbon.device.mgt.jaxrs.util.DeviceMgtAPIUtils; import javax.ws.rs.core.Response; +import java.util.ArrayList; import java.util.List; public class GroupManagementAdminServiceImpl implements GroupManagementAdminService { @@ -47,14 +48,15 @@ public class GroupManagementAdminServiceImpl implements GroupManagementAdminServ request.setOwner(owner); PaginationResult deviceGroupsResult = DeviceMgtAPIUtils.getGroupManagementProviderService() .getGroups(request); - if (deviceGroupsResult.getData() != null && deviceGroupsResult.getRecordsTotal() > 0) { - DeviceGroupList deviceGroupList = new DeviceGroupList(); + DeviceGroupList deviceGroupList = new DeviceGroupList(); + if (deviceGroupsResult.getData() != null) { deviceGroupList.setList(deviceGroupsResult.getData()); deviceGroupList.setCount(deviceGroupsResult.getRecordsTotal()); - return Response.status(Response.Status.OK).entity(deviceGroupList).build(); } else { - return Response.status(Response.Status.NOT_FOUND).build(); + deviceGroupList.setList(new ArrayList<>()); + deviceGroupList.setCount(0); } + return Response.status(Response.Status.OK).entity(deviceGroupList).build(); } catch (GroupManagementException e) { String msg = "ErrorResponse occurred while retrieving all groups."; log.error(msg, e);