added swagger annotation to the interfaces

revert-70aa11f8
Madhawa 9 years ago
parent 36c3a057dc
commit b407797ab0

@ -19,10 +19,18 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 org.wso2.carbon.certificate.mgt.core.dto.CertificateResponse;
import org.wso2.carbon.device.mgt.common.PaginationResult;
import org.wso2.carbon.device.mgt.jaxrs.api.common.MDMAPIException; import org.wso2.carbon.device.mgt.jaxrs.api.common.MDMAPIException;
import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
import org.wso2.carbon.device.mgt.jaxrs.beans.EnrollmentCertificate; import org.wso2.carbon.device.mgt.jaxrs.beans.EnrollmentCertificate;
import javax.ws.rs.*; import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -43,8 +51,21 @@ public interface Certificate {
*/ */
@POST @POST
@Path("saveCertificate") @Path("saveCertificate")
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "POST",
value = "Adding an SSL Certificate",
notes = "Add a new SSL certificate to the client end database",
response = MediaType.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Added successfully"),
@ApiResponse(code = 500, message = "Error occurred while saving the certificate")
})
Response saveCertificate(@HeaderParam("Accept") String acceptHeader, Response saveCertificate(@HeaderParam("Accept") String acceptHeader,
EnrollmentCertificate[] enrollmentCertificates); @ApiParam(name = "enrollmentCertificates", value = "certificate with serial, "
+ "pem and tenant id", required = true) EnrollmentCertificate[]
enrollmentCertificates);
/** /**
* Get a certificate when the serial number is given. * Get a certificate when the serial number is given.
@ -54,7 +75,21 @@ public interface Certificate {
*/ */
@GET @GET
@Path("{serialNumber}") @Path("{serialNumber}")
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting Details of an SSL Certificate",
notes = "Get the client side SSL certificate details",
response = CertificateResponse.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 400, message = "Notification status updated successfully"),
@ApiResponse(code = 500, message = "Error occurred while converting PEM file to X509Certificate")
})
Response getCertificate(@HeaderParam("Accept") String acceptHeader, Response getCertificate(@HeaderParam("Accept") String acceptHeader,
@ApiParam(name = "serialNumber", value = "Provide the serial number of the "
+ "certificate that you wish to get the details of", required = true)
@PathParam("serialNumber") String serialNumber); @PathParam("serialNumber") String serialNumber);
/** /**
@ -67,13 +102,46 @@ public interface Certificate {
*/ */
@GET @GET
@Path("paginate") @Path("paginate")
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting the Certificate Details in a Paginated Manner",
notes = "You will have many certificates used for mutual SSL. In a situation where you wish to "
+ "view all the certificate details, it is not feasible to show all the details on one "
+ "page therefore the details are paginated",
response = PaginationResult.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 400, message = "Invalid start index"),
@ApiResponse(code = 400, message = "Invalid length value"),
@ApiResponse(code = 500, message = "Error occurred while fetching all certificates")
})
Response getAllCertificates(@HeaderParam("Accept") String acceptHeader, Response getAllCertificates(@HeaderParam("Accept") String acceptHeader,
@QueryParam("start") int startIndex, @QueryParam("length") int length) @ApiParam(name = "start",
throws MDMAPIException; value = "Provide the starting pagination index as the value", required = true)
@QueryParam("start") int startIndex,
@ApiParam(name = "length", value = "Provide how many certificate details you"
+ " require from the starting pagination index as the value",
required = true) @QueryParam("length") int length) throws MDMAPIException;
@DELETE @DELETE
@Path("{serialNumber}") @Path("{serialNumber}")
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "DELETE",
value = "Deleting an SSL Certificate",
notes = "Delete an SSL certificate that's on the client end",
response = boolean.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 400, message = "Invalid start index"),
@ApiResponse(code = 500, message = "Error when deleting the certificate"
) })
Response removeCertificate(@HeaderParam("Accept") String acceptHeader, Response removeCertificate(@HeaderParam("Accept") String acceptHeader,
@PathParam("serialNumber") String serialNumber) throws MDMAPIException; @ApiParam(name = "serialNumber", value = "Provide the serial number of the "
+ "certificate that you wish to delete", required = true)
@PathParam("serialNumber") String serialNumber) throws MDMAPIException;
} }

@ -19,9 +19,15 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 org.wso2.carbon.device.mgt.common.configuration.mgt.TenantConfiguration; import org.wso2.carbon.device.mgt.common.configuration.mgt.TenantConfiguration;
import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
import javax.ws.rs.*; import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -35,12 +41,49 @@ import javax.ws.rs.core.Response;
public interface Configuration { public interface Configuration {
@POST @POST
Response saveTenantConfiguration(TenantConfiguration configuration); @ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "POST",
value = "Configuring general platform settings",
notes = "Configure the general platform settings using this REST API",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Tenant configuration saved successfully"),
@ApiResponse(code = 500, message = "Error occurred while saving the tenant configuration")
})
Response saveTenantConfiguration(@ApiParam(name = "configuration", value = "The required properties to "
+ "update the platform configurations the as the <JSON_PAYLOAD> value",
required = true) TenantConfiguration configuration);
@GET @GET
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting General Platform Configurations",
notes = "Get the general platform level configuration details using this REST API",
response = TenantConfiguration.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the tenant configuration")
})
Response getConfiguration(); Response getConfiguration();
@PUT @PUT
Response updateConfiguration(TenantConfiguration configuration); @ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "PUT",
value = "Updating General Platform Configurations",
notes = "Update the notification frequency using this REST API",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Tenant configuration updated successfully"),
@ApiResponse(code = 500, message = "Error occurred while updating the tenant configuration")
})
Response updateConfiguration(@ApiParam(name = "configuration", value = "The required properties to update"
+ " the platform configurations the as the <JSON_PAYLOAD> value",
required = true) TenantConfiguration configuration);
} }

@ -20,6 +20,7 @@ package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.*; import io.swagger.annotations.*;
import org.wso2.carbon.device.mgt.common.EnrolmentInfo; import org.wso2.carbon.device.mgt.common.EnrolmentInfo;
import org.wso2.carbon.device.mgt.core.dto.DeviceType;
import javax.ws.rs.*; import javax.ws.rs.*;
import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MediaType;
@ -43,22 +44,37 @@ public interface Device {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Returns the set of devices that matches a given device type, user, role, " value = "Returns device list",
+ "enrollment status, ownership type", notes = "Returns the set of devices that matches a given device type, user, role, "
notes = "Returns 500 if the operation fails", + "enrollment status, ownership type",
response = Device.class, response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List") responseContainer = "List")
@ApiResponses(value = { @ApiResponse(code = 200, message = "List of Devices"), @ApiResponses(value = {
@ApiResponse(code = 500, message = "Server Error") }) @ApiResponse(code = 200, message = "List of Devices"),
Response getAllDevices( @ApiResponse(code = 500, message = "Error occurred while fetching the device list")
@ApiParam(name = "type", value = "Provide the device type, such as ios, android or windows", required = true) @QueryParam("type") String type, })
@ApiParam(name = "user", value = "Get the details of the devices registered to a user by providing the user name", required = true) @QueryParam("user") String user, Response getAllDevices(@ApiParam(name = "type", value = "Provide the device type, such as ios, android or"
@ApiParam(name = "role", value = "Get the details of the devices registered to a specific role by providing the role name", required = true) @QueryParam("role") String role, + " windows", required = true) @QueryParam("type") String type,
@ApiParam(name = "status", value = "Provide the device status details, such as active or inactive", required = true) @QueryParam("status") EnrolmentInfo.Status status, @ApiParam(name = "user", value = "Get the details of the devices registered to a "
@ApiParam(name = "start", value = "Provide the starting pagination index", required = true) @QueryParam("start") int startIdx, + "user by providing the user name", required = true) @QueryParam("user")
@ApiParam(name = "length", value = "Provide how many device details you require from the starting pagination index", required = true) @QueryParam("length") int length, String user,
@ApiParam(name = "device-name", value = "Provide the name of a registered device and receive the specified device details", required = true) @QueryParam("device-name") String deviceName, @ApiParam(name = "role", value = "Get the details of the devices registered to a "
@ApiParam(name = "ownership", value = "Provide the device ownership type and receive the specific device details", required = true) @QueryParam("ownership") EnrolmentInfo.OwnerShip ownership); + "specific role by providing the role name", required = true)
@QueryParam("role") String role,
@ApiParam(name = "status", value = "Provide the device status details, such as "
+ "active or inactive", required = true) @QueryParam("status")
EnrolmentInfo.Status status,
@ApiParam(name = "start", value = "Provide the starting pagination index",
required = true) @QueryParam("start") int startIdx,
@ApiParam(name = "length", value = "Provide how many device details you require "
+ "from the starting pagination index", required = true)
@QueryParam("length") int length,
@ApiParam(name = "device-name", value = "Provide the name of a registered device "
+ "and receive the specified device details", required = true)
@QueryParam("device-name") String deviceName,
@ApiParam(name = "ownership", value = "Provide the device ownership type and "
+ "receive the specific device details", required = true)
@QueryParam("ownership") EnrolmentInfo.OwnerShip ownership);
/** /**
* Fetch device details for a given device type and device Id. * Fetch device details for a given device type and device Id.
@ -66,14 +82,6 @@ public interface Device {
* @return Device wrapped inside Response * @return Device wrapped inside Response
*/ */
@GET @GET
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Fetch device details for a given device type and device Id",
notes = "Returns 500 if the operation fails",
response = Device.class)
@ApiResponses(value = { @ApiResponse(code = 200, message = "Matching Device"),
@ApiResponse(code = 500, message = "Server Error") })
@Path("view") @Path("view")
@Produces({ MediaType.APPLICATION_JSON }) @Produces({ MediaType.APPLICATION_JSON })
Response getDevice(@QueryParam("type") String type, @QueryParam("id") String id); Response getDevice(@QueryParam("type") String type, @QueryParam("id") String id);
@ -104,14 +112,16 @@ public interface Device {
* @return device count * @return device count
*/ */
@GET @GET
@Path("count")
@ApiOperation( @ApiOperation(
httpMethod = "GET", httpMethod = "GET",
value = "Returns the current device count", value = "Getting the Device Count",
notes = "Returns 500 if the operation fails", notes = "Get the number of devices that are registered with WSO2 EMM.",
response = Integer.class) response = Integer.class)
@ApiResponses(value = { @ApiResponse(code = 200, message = "Device count"), @ApiResponses(value = {
@ApiResponse(code = 500, message = "Server Error") }) @ApiResponse(code = 200, message = "Device count"),
@Path("count") @ApiResponse(code = 500, message = "Error occurred while fetching the device count")
})
Response getDeviceCount(); Response getDeviceCount();
/** /**
@ -123,8 +133,21 @@ public interface Device {
*/ */
@GET @GET
@Path("name/{name}/{tenantDomain}") @Path("name/{name}/{tenantDomain}")
Response getDevicesByName(@PathParam("name") String deviceName, @ApiOperation(
@PathParam("tenantDomain") String tenantDomain); httpMethod = "GET",
value = "Get the device details of a specific device via the REST API",
notes = "Get the device details of a specific device",
response = DeviceType.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of devices"),
@ApiResponse(code = 500, message = "Error occurred while fetching the devices list of device name")
})
Response getDevicesByName(@ApiParam(name = "name", value = "The name of the device or windows",
required = true) @PathParam("name") String deviceName,
@ApiParam(name = "tenantDomain", value = "Tenant domain name. The default "
+ "tenant domain of WSO2 EMM is carbon.super", required = true)
@PathParam("tenantDomain") String tenantDomain);
/** /**
* Get the list of available device types. * Get the list of available device types.
@ -133,6 +156,16 @@ public interface Device {
*/ */
@GET @GET
@Path("types") @Path("types")
@ApiOperation(
httpMethod = "GET",
value = "Getting Details of the Devices Supported via WSO2 EMM",
notes = "You are able to register Android, iOS and Windows devices with WSO2 EMM. This API will "
+ "retrieve the device type details that can register with the EMM",
response = DeviceType.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of devices based on the type"),
@ApiResponse(code = 500, message = "Error occurred while fetching the list of device types") })
Response getDeviceTypes(); Response getDeviceTypes();
/** /**

@ -19,10 +19,18 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 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.jaxrs.beans.UserCredentialWrapper;
import javax.ws.rs.GET; import javax.ws.rs.GET;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.PathParam; import javax.ws.rs.PathParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -34,10 +42,41 @@ public interface DeviceInformation {
@GET @GET
@Path("{type}/{id}") @Path("{type}/{id}")
Response getDeviceInfo(@PathParam("type") String type, @PathParam("id") String id); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Get device information",
notes = "This will return device information such as CPU usage, memory usage etc.",
response = DeviceInfo.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 400, message = ""),
@ApiResponse(code = 500, message = "Internal Server Error")
})
Response getDeviceInfo(@ApiParam(name = "type", value = "Provide the device type, such as ios, android "
+ "or windows", required = true) @PathParam("type") String type,
@ApiParam(name = "id", value = "Provide the device identifier", required = true)
@PathParam("id") String id);
@GET @GET
@Path("location/{type}/{id}") @Path("location/{type}/{id}")
Response getDeviceLocation(@PathParam("type") String type, @PathParam("id") String id); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Get the device location",
notes = "This will return the device location including latitude and longitude as well the "
+ "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")
})
Response getDeviceLocation(@ApiParam(name = "type", value = "Provide the device type, such as ios, "
+ "android or windows", required = true) @PathParam("type") String type,
@ApiParam(name = "id", value = "Provide the device identifier",
required = true) @PathParam("id") String id);
} }

@ -19,7 +19,12 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 org.wso2.carbon.device.mgt.common.notification.mgt.Notification; import org.wso2.carbon.device.mgt.common.notification.mgt.Notification;
import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
import javax.ws.rs.Consumes; import javax.ws.rs.Consumes;
import javax.ws.rs.GET; import javax.ws.rs.GET;
@ -28,6 +33,7 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.PathParam; import javax.ws.rs.PathParam;
import javax.ws.rs.Produces; import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -41,18 +47,72 @@ import javax.ws.rs.core.Response;
public interface DeviceNotification { public interface DeviceNotification {
@GET @GET
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting all Device Notification Details",
notes = "Get the details of all notifications that were pushed to the device in WSO2 EMM using "
+ "this REST API",
response = Notification.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Notifications"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the notification list")
})
Response getNotifications(); Response getNotifications();
@GET @GET
@Path("{status}") @Path("{status}")
Response getNotificationsByStatus(@PathParam("status") Notification.Status status); @ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "GET",
value = "Getting the Device Notifications Filtered by the Status",
notes = "Get the details of all the unread notifications or the details of all the read "
+ "notifications using this REST API",
response = Notification.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "List of Notifications"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the notification list")
})
Response getNotificationsByStatus(@ApiParam(name = "status", value = "Provide the notification status as"
+ " the value for {status}", required = true)
@PathParam("status") Notification.Status status);
@PUT @PUT
@Path("{id}/{status}") @Path("{id}/{status}")
Response updateNotificationStatus(@PathParam("id") int id, @ApiOperation(
@PathParam("status") Notification.Status status); consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "PUT",
value = "Updating the Device Notification Status",
notes = "When a user has read the the device notification the device notification status must "
+ "change from NEW to CHECKED. Update the device notification status using this REST API",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Notification status updated successfully"),
@ApiResponse(code = 500, message = "Error occurred while updating notification status")
})
Response updateNotificationStatus( @ApiParam(name = "id", value = "Provide the ID of the notification"
+ " you wish you update", required = true) @PathParam("id") int id,
@ApiParam(name = "status", value = "Provide the notification status as"
+ " the value", required = true) @PathParam("status")
Notification.Status status);
@POST @POST
@ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "POST",
value = "Sending a Device Notification",
notes = "Notify users on device operation failures and other information using this REST API",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "NNotification has added successfully"),
@ApiResponse(code = 500, message = "Error occurred while updating notification status")
})
Response addNotification(Notification notification); Response addNotification(Notification notification);
} }

@ -19,9 +19,16 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 org.wso2.carbon.device.mgt.common.PaginationResult;
import org.wso2.carbon.device.mgt.common.device.details.DeviceWrapper;
import org.wso2.carbon.device.mgt.common.search.SearchContext; import org.wso2.carbon.device.mgt.common.search.SearchContext;
import javax.ws.rs.GET; import javax.ws.rs.GET;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -32,5 +39,17 @@ import javax.ws.rs.core.Response;
public interface DeviceSearch { public interface DeviceSearch {
@GET @GET
Response getDeviceInfo(SearchContext searchContext); @ApiOperation(
consumes = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Advanced Search for Devices via the Console",
notes = "Carry out an advanced search via the EMM console",
response = DeviceWrapper.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 500, message = "Error occurred while searching the device information")
})
Response getDeviceInfo(@ApiParam(name = "enrollmentCertificates", value = "List of search conditions",
required = true) SearchContext searchContext);
} }

@ -19,6 +19,12 @@
package org.wso2.carbon.device.mgt.jaxrs.api; package org.wso2.carbon.device.mgt.jaxrs.api;
import io.swagger.annotations.Api; 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 org.apache.axis2.databinding.types.soapencoding.Integer;
import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper;
import org.wso2.carbon.device.mgt.jaxrs.beans.UserWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.UserWrapper;
@ -44,29 +50,111 @@ public interface User {
@POST @POST
@Consumes({ MediaType.APPLICATION_JSON}) @Consumes({ MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response addUser(UserWrapper userWrapper); @ApiOperation(
consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Adding a User via the REST API",
notes = "Adds a new user to WSO2 EMM using this REST API")
@ApiResponses(value = {
@ApiResponse(code = 201, message = "Created"),
@ApiResponse(code = 500, message = "Exception in trying to add user by username: 'username'")
})
Response addUser(@ApiParam(name = "userWrapper", value = "Includes the required properties to add a user"
+ " as the <JSON_PAYLOAD> value", required = true) UserWrapper userWrapper);
@GET @GET
@Path("view") @Path("view")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response getUser(@QueryParam("username") String username); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Details of a User",
notes = "If you wish to get the details of a specific user that is registered with WSO2 EMM,"
+ " you can do so using the REST API",
response = UserWrapper.class)
@ApiResponses(value = {
@ApiResponse(code = 201, message = "User information was retrieved successfully"),
@ApiResponse(code = 400, message = "User by username: 'username' does not exist"),
@ApiResponse(code = 500, message = "Exception in trying to retrieve user by username: 'username'")
})
Response getUser(@ApiParam(name = "username", value = "Provide the name of the user you wish to get the"
+ " details of as the value", required = true)
@QueryParam("username") String username);
@PUT @PUT
@Consumes({MediaType.APPLICATION_JSON}) @Consumes({MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response updateUser(UserWrapper userWrapper, @QueryParam("username") String username); @ApiOperation(
consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
httpMethod = "PUT",
value = "Updating Details of a User",
notes = "There will be situations where you will want to update the user details. In such "
+ "situation you can update the user details using this REST API")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "User by username: 'username' was successfully updated"),
@ApiResponse(code = 409, message = "User by username: 'username' doesn't exists. Therefore, "
+ "request made to update user was refused"),
@ApiResponse(code = 500, message = "Exception in trying to update user by username: 'username'")
})
Response updateUser(@ApiParam(name = "userWrapper", value = "Provide the name of the user you wish to get"
+ " the details of as the value", required = true) UserWrapper userWrapper,
@ApiParam(name = "username", value = "Provide the name of the user you wish to get "
+ "the details of as the value", required = true)
@QueryParam("username") String username);
@DELETE @DELETE
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response removeUser(@QueryParam("username") String username); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "DELETE",
value = "Deleting a User",
notes = "In a situation where an employee leaves the organization you will need to remove the"
+ " user details from WSO2 EMM. In such situations you can use this REST API "
+ "to remove a user",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "User by username: 'username' was successfully removed"),
@ApiResponse(code = 400, message = "User by username: 'username' does not exist for removal"),
@ApiResponse(code = 500, message = "Exception in trying to remove user by username: 'username'")
})
Response removeUser(@ApiParam(name = "username", value = "Provide the name of the user you wish to delete"
+ " as the value for {username}", required = true)
@QueryParam("username") String username);
@GET @GET
@Path("roles") @Path("roles")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response getRoles(@QueryParam("username") String username); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting the Role Details of a User",
notes = "A user can be assigned to one or more role in WSO2 EMM. Using this REST API you are "
+ "able to get the role/roles a user is assigned to",
response = String.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "User roles obtained for user : 'username'"),
@ApiResponse(code = 400, message = "User by username: 'username' does not exist for role retrieval"),
@ApiResponse(code = 500, message = "Exception in trying to retrieve roles for user by username: 'username'")
})
Response getRoles(@ApiParam(name = "username", value = "Provide the user name of the user you wish to get"
+ " the role details", required = true) @QueryParam("username") String username);
@GET @GET
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Details of Users",
notes = "If you wish to get the details of all the user registered with WSO2 EMM, you can do so "
+ "using the REST API",
response = ResponsePayload.class)
@ApiResponses(value = {
@ApiResponse(code = 201, message = "All users were successfully retrieved"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of users")
})
Response getAllUsers(); Response getAllUsers();
@GET @GET
@ -76,41 +164,154 @@ public interface User {
@GET @GET
@Path("view-users") @Path("view-users")
Response getAllUsersByUsername(@QueryParam("username") String userName); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting User Details by Searching via the User Name",
notes = "You will have 100+ users registered with WSO2 EMM. If you wish to retrieve the user "
+ "details of a specific user, and you only remember part of the user's username, "
+ "you are able to retrieve the user details by giving a character or a few characters "
+ "in the username",
response = String.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "All users by username were successfully retrieved. Obtained"
+ " user count: 'count'"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of users")
})
Response getAllUsersByUsername(@ApiParam(name = "username", value = "Provide any user detail of the user"
+ " as the value for {username} to retrieve the user details, such "
+ "as email address, first name or last name", required = true)
@QueryParam("username") String userName);
@GET @GET
@Path("users-by-username") @Path("users-by-username")
Response getAllUserNamesByUsername(@QueryParam("username") String userName); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Searching for a User Name",
notes = "You will have 100+ users registered with WSO2 EMM. Therefore if you are unsure of the "
+ "user name of a user and need to retrieve the details of a specific user, you can "
+ "search for that user by giving a character or a few characters in the username. "
+ "You will be given a list of users having the user name with the exact order of the "
+ "characters you provided",
response = String.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "All users by username were successfully retrieved. Obtained"
+ " user count: 'count'"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of users")
})
Response getAllUserNamesByUsername(@ApiParam(name = "username", value = "Provide a character or a few "
+ "character in the user name as the value for {username}",
required = true) @QueryParam("username") String userName);
@POST @POST
@Path("email-invitation") @Path("email-invitation")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response inviteExistingUsersToEnrollDevice(List<String> usernames); @ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Sending Enrollment Invitations to Users",
notes = "Send the users a mail inviting them to download the EMM mobile application on their "
+ "devices using this REST API")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Email invitation was successfully sent to user"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of users")
})
Response inviteExistingUsersToEnrollDevice(@ApiParam(name = "usernames", value = "List of the users to be"
+ " invited as the <JSON_PAYLOAD>", required = true)
List<String> usernames);
@GET @GET
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
@Path("devices") @Path("devices")
Response getAllDeviceOfUser(@QueryParam("username") String username, @QueryParam("start") int startIdx, @ApiOperation(
@QueryParam("length") int length); produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Device Details of a User",
notes = "If you wish to get the details of the devices enrolled by a specific user, you can do "
+ "so using this REST API",
response = org.wso2.carbon.device.mgt.common.Device.class,
responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 500, message = "Device management error")
})
Response getAllDeviceOfUser(@ApiParam(name = "username", value = "Provide the name of the user you wish "
+ "to get the details", required = true) @QueryParam("username")
String username,
@ApiParam(name = "start", value = "Provide the starting pagination index",
required = true) @QueryParam("start") int startIdx,
@ApiParam(name = "length", value = "Provide how many device details you "
+ "require from the starting pagination index", required = true)
@QueryParam("length") int length);
@GET @GET
@Path("count") @Path("count")
@ApiOperation(
httpMethod = "GET",
value = "Getting the User Count",
notes = "Get the number of users in WSO2 EMM",
response = Integer.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 500, message = "Error occurred while retrieving the list of users that exist"
+ " within the current tenant")
})
Response getUserCount(); Response getUserCount();
@PUT @PUT
@Path("{roleName}/users") @Path("{roleName}/users")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response updateRoles(@PathParam("username") String username, List<String> userList); Response updateRoles(@PathParam("username") String username, List<String> userList);
@POST @POST
@Path("change-password") @Path("change-password")
@Consumes({MediaType.APPLICATION_JSON}) @Consumes({MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response resetPassword(UserCredentialWrapper credentials); @ApiOperation(
consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Changing the User Password",
notes = "A user is able to change the password to secure their EMM profile via this REST API",
response = UserCredentialWrapper.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "UserImpl password by username: 'Username' was "
+ "successfully changed"),
@ApiResponse(code = 400, message = "Old password does not match"),
@ApiResponse(code = 400, message = "Could not change the password of the user: 'Username'. The"
+ " Character Encoding is not supported"),
@ApiResponse(code = 500, message = "Internal Server Error")
})
Response resetPassword(@ApiParam(name = "credentials", value = "Include the required properties to change"
+ " the user password as <JSON_PAYLOAD> value", required = true)
UserCredentialWrapper credentials);
@POST @POST
@Path("reset-password") @Path("reset-password")
@Consumes({MediaType.APPLICATION_JSON}) @Consumes({MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
Response resetPasswordByAdmin(UserCredentialWrapper credentials); @ApiOperation(
consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Resetting the User Password",
notes = "In a situation where you need to block a user from accessing their EMM profile, "
+ "the EMM administrator is able to reset the password. This will change the user's "
+ "password and the user will not be able to able to login to the account as he/she is "
+ "not aware of the new password.",
response = UserCredentialWrapper.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "UserImpl password by username: 'Username' was "
+ "successfully changed"),
@ApiResponse(code = 400, message = "Old password does not match"),
@ApiResponse(code = 400, message = "Could not change the password of the user: 'Username'. The"
+ " Character Encoding is not supported"),
@ApiResponse(code = 500, message = "Internal Server Error")
})
Response resetPasswordByAdmin(@ApiParam(name = "credentials", value = "Include the required properties "
+ "to change a user password as <JSON_PAYLOAD> value",
required = true) UserCredentialWrapper credentials);
} }

@ -53,7 +53,7 @@ import java.util.List;
@SuppressWarnings("NonJaxWsWebServices") @SuppressWarnings("NonJaxWsWebServices")
@Produces({"application/json", "application/xml"}) @Produces({"application/json", "application/xml"})
@Consumes({ "application/json", "application/xml" }) @Consumes({ "application/json", "application/xml" })
public class CertificateImpl implements Certificate{ public class CertificateImpl implements Certificate {
private static Log log = LogFactory.getLog(OperationImpl.class); private static Log log = LogFactory.getLog(OperationImpl.class);

Loading…
Cancel
Save