Updated swagger docs

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}")

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.")
+                               value = "The starting pagination index for the complete list of qualified items.",
-                       @QueryParam("offset") int offset,
+                               defaultValue = "0")
+                       @QueryParam("offset")
+                               int offset,
                        @ApiParam(
                                name = "limit",
-                               value = "Maximum size of resource array to return.")
+                               value = "Provide how many device details you require from the starting pagination index/offset.",
-                       @QueryParam("limit") int limit);
+                               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.")
+                                       value = "The starting pagination index for the complete list of qualified items.",
-                               @QueryParam("offset") int offset,
+                                       defaultValue = "0")
+                               @QueryParam("offset")
+                                       int offset,
                                @ApiParam(
                                        name = "limit",
-                                       value = "Maximum size of resource array to return.")
+                                       value = "Provide how many device details you require from the starting pagination index/offset.",
-                               @QueryParam("limit") int limit);
+                                       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.")
+                    value = "Id of the device.",
-            @QueryParam("deviceId") String deviceId,
+                    required = true)
+            @QueryParam("deviceId")
+                    String deviceId,
             @ApiParam(
                     name = "deviceType",
-                    value = "Type of the device.")
+                    value = "Type of the device.",
-            @QueryParam("deviceType") String deviceType);
+                    required = true)
+            @QueryParam("deviceType")
+                    String deviceType);
 
 }

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.")
+                               value = "The starting pagination index for the complete list of qualified items.",
-                       @QueryParam("offset") int offset,
+                               defaultValue = "0")
+                       @QueryParam("offset")
+                               int offset,
                        @ApiParam(
                                name = "limit",
-                               value = "Maximum size of resource array to return.")
+                               value = "Provide how many device details you require from the starting pagination index/offset.",
-                       @QueryParam("limit") int limit);
+                               defaultValue = "5")
+                       @QueryParam("limit")
+                               int limit);
 
     @Path("/count")
     @GET

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) {

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);
-            if (deviceGroupsResult.getData() != null && deviceGroupsResult.getRecordsTotal() > 0) {
             DeviceGroupList deviceGroupList = new DeviceGroupList();
+            if (deviceGroupsResult.getData() != null && deviceGroupsResult.getRecordsTotal() > 0) {
                 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<String> groupRoles = DeviceMgtAPIUtils.getGroupManagementProviderService().getRoles(groupId);
-
-            if(groupRoles != null && groupRoles.size() > 0) {
             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<String>());
+                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<Device> deviceList = service.getDevices(groupId, offset, limit);
-            if (deviceList != null && deviceList.size() > 0) {
+            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<Device>());
             }
+            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<DeviceGroup> 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();
         }

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();
+            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);