community
/
device-mgt-core
12
0
Fork 47
Code Issues Pull Requests 26 Packages Projects Releases Wiki Activity

adding swagger annotations for device and activity APIs.

Browse Source
merge-requests/7/head
inoshperera 9 years ago
parent 29b3b965b0
commit 2959c05e1a
4 changed files with 181 additions and 80 deletions
Show Stats Download Patch File Download Diff File

10
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java
Unescape View File

@ -28,6 +28,9 @@ import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
/**
* Activity related REST-API implementation.
*/
@Path("/activities")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ -40,12 +43,11 @@ public interface ActivityInfoProviderService {
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "POST",
value = "Retrieving the operation details.",
notes = "This will return the operation details including the responses from the devices")
@ApiResponses(value = {@ApiResponse(code = 200, message = "Activity details provided successfully.."),
notes = "This will return the operation details including the responses from the devices.")
@ApiResponses(value = {@ApiResponse(code = 200, message = "Activity details provided successfully."),
@ApiResponse(code = 500, message = "Error occurred while fetching the activity for the supplied id.")})
@Permission(scope = "operation-view", permissions = {"/permission/admin/device-mgt/admin/devices/view"})
Response getActivity(
@ApiParam(name = "id", value = "Provide activity id {id} as ACTIVITY_(number)",
Response getActivity(@ApiParam(name = "id", value = "Activity id of the operation/activity to be retrieved",
required = true) @PathParam("id") String id);
}

211
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java
Unescape View File

@ -37,6 +37,9 @@ import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.List;
/**
* Device related REST-API implementation. This can be used to manipulated device related details.
*/
@Path("/devices")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ -46,31 +49,46 @@ public interface DeviceManagementService {
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Returns device list",
notes = "Returns all devices enrolled with the system",
value = "Get the device list.",
notes = "Returns all devices enrolled with the system.",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.", response = org.wso2.carbon
.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device has currently been under the provided type."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevices(@QueryParam("offset") int offset, @QueryParam("limit") int limit);
Response getDevices(
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@GET
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Returns device list",
notes = "Returns all devices enrolled with the system",
value = "Get the device list corresponding to a device type.",
notes = "Returns all devices enrolled with the system under the provided type.",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.", response = org.wso2.carbon
.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device has currently been under the provided type."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevices(@QueryParam("type") String type, @QueryParam("offset") int offset,
Response getDevices(
@ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true)
@QueryParam ("type") String type,
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@POST
@ -78,67 +96,95 @@ public interface DeviceManagementService {
consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Get devices information from the supplied device identifies",
value = "Get devices information from the supplied device identifies.",
notes = "This will return device information such as CPU usage, memory usage etc for supplied device " +
"identifiers.",
response = DeviceInfo.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 500, message = "Internal Server Error")
@ApiResponse(code = 200, message = "Successfully fetched device information.", response = DeviceInfo.class,
responseContainer = "List"),
@ApiResponse(code = 404, message = "No device information is available for the device list submitted."),
@ApiResponse(code = 500, message = "Error occurred while getting the device information.")
})
@Permission(scope = "device-info", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevices(List<DeviceIdentifier> deviceIds);
Response getDevicesInfo(
@ApiParam(name = "deviceIds", value = "List of device identifiers",
required = true) List<DeviceIdentifier> deviceIds);
@GET
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Returns device list",
notes = "Returns the set of devices that matches a given username",
value = "Get the device list of a user.",
notes = "Returns the set of devices that matches a given username.",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.", response = org.wso2.carbon
.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device has currently been enrolled by the user."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDeviceByUsername(@QueryParam("user") String user, @QueryParam("offset") int offset,
Response getDeviceByUsername(
@ApiParam(name = "user", value = "Username of owner of the devices.", required = true)
@QueryParam("user") String user,
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@GET
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Returns device list",
notes = "Returns the set of devices that matches a given role",
value = "Returns device list in a role.",
notes = "Returns the set of devices that matches a given role.",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.", response = org.wso2.carbon
.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device has currently been enrolled under the role."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevicesByRole(@QueryParam("roleName") String roleName, @QueryParam("offset") int offset,
Response getDevicesByRole(
@ApiParam(name = "roleName", value = "Role name of the devices to be fetched.", required = true)
@QueryParam("roleName") String roleName,
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@GET
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Returns device list",
notes = "Returns the set of devices that matches a given ownership scheme",
value = "Returns device list of an ownership scheme.",
notes = "Returns the set of devices that matches a given ownership scheme.",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.", response = org.wso2.carbon
.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device has currently been enrolled under the given ownership " +
"scheme."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevicesByOwnership(@QueryParam("ownership") EnrolmentInfo.OwnerShip ownership,
@QueryParam("offset") int offset, @QueryParam("limit") int limit);
Response getDevicesByOwnership(
@ApiParam(name = "ownership", value = "Ownership of the devices to be fetched registered under.",
required = true)
@QueryParam("ownership") EnrolmentInfo.OwnerShip ownership,
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@GET
@ApiOperation(
@ -149,12 +195,20 @@ public interface DeviceManagementService {
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiResponse(code = 200, message = "Successfully fetched the list of devices.",
response = org.wso2.carbon.device.mgt.common.Device.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No device is currently in the given enrollment status."),
@ApiResponse(code = 500, message = "Error occurred while fetching the device list.")
})
@Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDevicesByEnrollmentStatus(@QueryParam("status") EnrolmentInfo.Status status,
@QueryParam("offset") int offset, @QueryParam("limit") int limit);
Response getDevicesByEnrollmentStatus(
@ApiParam(name = "status", value = "Enrollment status of devices to be fetched.", required = true)
@QueryParam("status") EnrolmentInfo.Status status,
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit);
@GET
@Permission(scope = "device-view", permissions = {
@ -167,18 +221,22 @@ public interface DeviceManagementService {
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Get the device location",
value = "Get the device location of a given device and a device type.",
notes = "This will return the device location including latitude and longitude as well the "
+ "physical address",
+ "physical address.",
response = DeviceLocation.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 500, message = "Internal Server Error")
@ApiResponse(code = 200, message = "Successfully fetched the device location.",
response = DeviceLocation.class),
@ApiResponse(code = 404, message = "Location details are not available for the given device."),
@ApiResponse(code = 500, message = "Error occurred while getting the device location.")
})
@Permission(scope = "device-info", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response getDeviceLocation(@PathParam("type") String type, @PathParam("id") String id);
Response getDeviceLocation(
@ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "type", value = "The device identifier of the device.", required = true)
@PathParam("id") String id);
@GET
@Path("/{type}/{id}/features")
@ -192,12 +250,17 @@ public interface DeviceManagementService {
" such as iOS, Android or Windows.",
response = org.wso2.carbon.device.mgt.common.Feature.class,
responseContainer = "List")
@ApiResponses(value = { @ApiResponse(code = 200, message = "List of Features"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of features" +
".") })
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successfully fetched the features.",
response = org.wso2.carbon.device.mgt.common.Feature.class, responseContainer = "List"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of features.") })
@Permission(scope = "device-search", permissions = {"/permission/admin/device-mgt/admin/devices/view",
"/permission/admin/device-mgt/user/devices/view"})
Response getFeaturesOfDevice(@PathParam("type") String type, @PathParam("id") String id);
Response getFeaturesOfDevice(
@ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "type", value = "The device identifier of the device.", required = true)
@PathParam("id") String id);
@POST
@Path("/search-devices")
@ -205,16 +268,18 @@ public interface DeviceManagementService {
produces = MediaType.APPLICATION_JSON,
consumes = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Advanced Search for Devices via the Console",
notes = "Carry out an advanced search via the EMM console",
value = "Advanced search for devices.",
notes = "Carry out an advanced search of devices.",
response = DeviceWrapper.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = DeviceWrapper.class, responseContainer = "List"),
@ApiResponse(code = 500, message = "Error occurred while searching the device information")
@ApiResponse(code = 200, message = "Successfully fetched matching devices.", response = DeviceWrapper.class,
responseContainer = "List"),
@ApiResponse(code = 500, message = "Error occurred while searching the device information.")
})
@Permission(scope = "device-search", permissions = {"/permission/admin/device-mgt/admin/devices/list"})
Response searchDevices(@ApiParam(name = "filtering rules", value = "List of search conditions",
Response searchDevices(
@ApiParam(name = "searchContext", value = "List of search conditions.",
required = true) SearchContext searchContext);
@GET
@ -223,21 +288,23 @@ public interface DeviceManagementService {
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting Installed Application Details of a Device.",
value = "Getting installed application details of a device.",
responseContainer = "List",
notes = "Get the list of applications that a device has subscribed.",
response = Application.class)
@ApiResponses(value = {@ApiResponse(code = 200, message = "List of installed application details of a device.", response = Application.class, responseContainer = "List"),
@ApiResponse(code = 500, message = "Error occurred while fetching the apps of the device" +
".")})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of installed application details of a device.",
response = Application.class, responseContainer = "List"),
@ApiResponse(code = 404, message = "No installed applications found on the device searched."),
@ApiResponse(code = 500, message = "Error occurred while fetching the apps of the device.")})
@Permission(scope = "operation-view", permissions = {
"/permission/admin/device-mgt/admin/devices/view",
"/permission/admin/device-mgt/user/devices/view"})
Response getInstalledApplications(
@ApiParam(name = "type", value = "Define the device type as the value for {type}. " +
"Example: ios, android or windows.", required = true)
@PathParam("type") String type, @ApiParam(name = "id", value = "Define the device ID",
required = true) @PathParam("id") String id);
@ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "type", value = "The device identifier of the device.", required = true)
@PathParam("id") String id);
@GET
@ -246,21 +313,29 @@ public interface DeviceManagementService {
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting Paginated Details for Operations on a Device.",
value = "Getting paginated details for operations on a device.",
notes = "You will carry out many operations on a device. In a situation where you wish to view the all" +
" the operations carried out on a device it is not feasible to show all the details on one page" +
" therefore the details are paginated." +
" Example: You carry out 21 operations via a given device. When you wish to see the operations " +
"carried out, the details of the 21 operations will be broken down into 3 pages with 10 operation" +
" details per page.",
" therefore the details are paginated.",
response = org.wso2.carbon.device.mgt.common.operation.mgt.Operation.class)
@ApiResponses(value = {@ApiResponse(code = 200, message = "List of Operations on a device."),
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Operations on a device.",
response = org.wso2.carbon.device.mgt.common.operation.mgt.Operation.class,
responseContainer = "List"),
@ApiResponse(code = 500, message = "Error occurred while fetching the operations for the " +
"device.")})
@Permission(scope = "operation-view", permissions = {
"/permission/admin/device-mgt/admin/devices/view",
"/permission/admin/device-mgt/user/devices/view"})
Response getDeviceOperations(@QueryParam("offset") int offset, @QueryParam("limit") int limit,
@PathParam("type") String type, @PathParam("id") String id);
Response getDeviceOperations(
@ApiParam(name = "offset", value = "Starting pagination index.",required = true)
@QueryParam("offset") int offset,
@ApiParam(name = "limit", value = "How many device details are required from the starting pagination " +
"index.", required = true)
@QueryParam("limit") int limit,
@ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "type", value = "The device identifier of the device.", required = true)
@PathParam("id") String id);
}

6
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/ActivityProviderServiceImpl.java
Unescape View File

@ -18,7 +18,6 @@
*/
package org.wso2.carbon.device.mgt.jaxrs.service.impl;
import io.swagger.annotations.ApiParam;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.wso2.carbon.device.mgt.common.operation.mgt.Operation;
@ -27,6 +26,7 @@ import org.wso2.carbon.device.mgt.core.service.DeviceManagementProviderService;
import org.wso2.carbon.device.mgt.jaxrs.service.api.ActivityInfoProviderService;
import org.wso2.carbon.device.mgt.jaxrs.util.DeviceMgtAPIUtils;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
@ -35,8 +35,8 @@ public class ActivityProviderServiceImpl implements ActivityInfoProviderService
private static final Log log = LogFactory.getLog(ActivityProviderServiceImpl.class);
@Override
public Response getActivity(@ApiParam(name = "id", value = "Provide activity id {id} as ACTIVITY_(number)",
required = true) @PathParam("id") String id) {
@Path("/{id}")
public Response getActivity(@PathParam("id") String id) {
Operation operation = null;
DeviceManagementProviderService dmService;
try {

28
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceManagementServiceImpl.java
Unescape View File

@ -23,6 +23,7 @@ import org.apache.commons.logging.LogFactory;
import org.wso2.carbon.device.mgt.common.*;
import org.wso2.carbon.device.mgt.common.app.mgt.Application;
import org.wso2.carbon.device.mgt.common.app.mgt.ApplicationManagementException;
import org.wso2.carbon.device.mgt.common.device.details.DeviceInfo;
import org.wso2.carbon.device.mgt.common.device.details.DeviceLocation;
import org.wso2.carbon.device.mgt.common.device.details.DeviceWrapper;
import org.wso2.carbon.device.mgt.common.operation.mgt.Operation;
@ -90,8 +91,22 @@ public class DeviceManagementServiceImpl implements DeviceManagementService {
@POST
@Override
public Response getDevices(List<DeviceIdentifier> deviceIds) {
return null;
public Response getDevicesInfo(List<DeviceIdentifier> deviceIds) {
DeviceInformationManager informationManager;
List<DeviceInfo> deviceInfo;
try {
informationManager = DeviceMgtAPIUtils.getDeviceInformationManagerService();
deviceInfo = informationManager.getDevicesInfo(deviceIds);
if (deviceInfo == null) {
return Response.status(Response.Status.NOT_FOUND).entity("No device information is available for the " +
"device list submitted").build();
}
} catch (DeviceDetailsMgtException e) {
String msg = "Error occurred while getting the device information.";
log.error(msg, e);
return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(msg).build();
}
return Response.status(Response.Status.OK).entity(deviceInfo).build();
}
@GET
@ -206,6 +221,11 @@ public class DeviceManagementServiceImpl implements DeviceManagementService {
try {
informationManager = DeviceMgtAPIUtils.getDeviceInformationManagerService();
deviceLocation = informationManager.getDeviceLocation(new DeviceIdentifier(id, type));
if (deviceLocation == null || deviceLocation.getLatitude() == null ||
deviceLocation.getLongitude() == null) {
return Response.status(Response.Status.NOT_FOUND).entity("Location details are not available for the " +
"given device id '" + id + "'").build();
}
} catch (DeviceDetailsMgtException e) {
String msg = "Error occurred while getting the last updated location of the '" + type + "' device, " +
"which carries the id '" + id + "'";
@ -267,6 +287,10 @@ public class DeviceManagementServiceImpl implements DeviceManagementService {
try {
amc = DeviceMgtAPIUtils.getAppManagementService();
applications = amc.getApplicationListForDevice(new DeviceIdentifier(id, type));
if (applications == null || applications.size() == 0) {
return Response.status(Response.Status.NOT_FOUND).entity("No installed applications found on the " +
"device searched").build();
}
} catch (ApplicationManagementException e) {
String msg = "Error occurred while fetching the apps of the '" + type + "' device, which carries " +
"the id '" + id + "'";

Write Preview
Loading…
Cancel
Save