Adding sawgger annotations to admin Jax-rs apis.

components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java

@@ -18,13 +18,14 @@
 
 package org.wso2.carbon.device.mgt.jaxrs.api;
 
-import io.swagger.annotations.Api;
+import io.swagger.annotations.*;
 
 import javax.ws.rs.Consumes;
 import javax.ws.rs.GET;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
 /**
@@ -43,6 +44,20 @@ public interface Feature {
      */
     @GET
     @Path("/{type}")
-    Response getFeatures(@PathParam("type") String type);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "GET",
+            value = "Get Feature Details of a Device",
+            notes = "WSO2 EMM features enable you to carry out many operations on a given device platform. " +
+                    "Using this REST API you can get the features that can be carried out on a preferred device type," +
+                    " 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" +
+                                                               ".") })
+    Response getFeatures(@ApiParam(name = "type", value = "Provide the device type, such as ios, android or windows",
+                                   required = true) @PathParam("type") String type);
 
 }

components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java

@@ -18,8 +18,11 @@
 
 package org.wso2.carbon.device.mgt.jaxrs.api;
 
-import io.swagger.annotations.Api;
+import io.swagger.annotations.*;
+import org.wso2.carbon.device.mgt.common.PaginationResult;
+import org.wso2.carbon.device.mgt.common.app.mgt.Application;
 import org.wso2.carbon.device.mgt.jaxrs.api.context.DeviceOperationContext;
+import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
 import org.wso2.carbon.device.mgt.jaxrs.beans.ApplicationWrapper;
 
 import javax.ws.rs.GET;
@@ -27,6 +30,7 @@ import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
 /**
@@ -41,13 +45,55 @@ public interface Operation {
 
     @GET
     @Path("paginate/{type}/{id}")
-    Response getDeviceOperations(@PathParam("type") String type, @PathParam("id") String id,
+    @ApiOperation(
-                                 @QueryParam("start") int startIdx, @QueryParam("length") int length,
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "GET",
+            value = "Getting Pagination 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.",
+            response = org.wso2.carbon.device.mgt.common.operation.mgt.Operation.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "List of Operations on a device."),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the operations for the " +
+                                                               "device.") })
+    Response getDeviceOperations(@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 = "start", value = "Provide the starting pagination index. Example 10",
+                                           required = true) @QueryParam("start") int startIdx,
+                                 @ApiParam(name = "length", value = "Provide how many device details you require from" +
+                                                                    " the starting pagination index. For example if " +
+                                                                    "you require the device details from the 10th " +
+                                                                    "pagination index to the 15th, " +
+                                                                    "you must define 10 as the value for start and 5 " +
+                                                                    "as the value for length.",
+                                           required = true) @QueryParam("length") int length,
                                  @QueryParam("search") String search);
 
     @GET
     @Path("{type}/{id}")
-    Response getDeviceOperations(@PathParam("type") String type, @PathParam("id") String id);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "GET",
+            value = "Getting Device Operation Details.",
+            responseContainer = "List",
+            notes = "Get the details of operations carried out on a selected device.",
+            response = org.wso2.carbon.device.mgt.common.operation.mgt.Operation.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "List of Operations on a device."),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the operations for the " +
+                                                               "device.") })
+    Response getDeviceOperations(@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);
 
     /* @deprecated */
     @POST
@@ -55,15 +101,58 @@ public interface Operation {
 
     @GET
     @Path("{type}/{id}/apps")
-    Response getInstalledApps(@PathParam("type") String type, @PathParam("id") String id);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "GET",
+            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."),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the apps of the device" +
+                                                               ".") })
+    Response getInstalledApps(@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);
 
     @POST
     @Path("installApp/{tenantDomain}")
-    Response installApplication(ApplicationWrapper applicationWrapper,
+    @ApiOperation(
-                                @PathParam("tenantDomain") String tenantDomain);
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "POST",
+            value = "Installing an Application on a Device.",
+            notes = "Install a selected application on a device.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Operation was successfully added to the queue."),
+                            @ApiResponse(code = 500, message = "Error occurred while saving the operation.") })
+    Response installApplication(@ApiParam(name = "applicationWrapper", value = "Details about the application and the" +
+                                                                               " users and roles it should be " +
+                                                                               "installed on.",
+                                          required = true) ApplicationWrapper applicationWrapper,
+                                @ApiParam(name = "tenantDomain", value = "Provide the tenant domain as the value for " +
+                                                                         "{tenantDomain}. The default tenant domain " +
+                                                                         "of WSO2 EMM is carbon.super.",
+                                          required = true) @PathParam("tenantDomain") String tenantDomain);
 
     @POST
     @Path("uninstallApp/{tenantDomain}")
-    Response uninstallApplication(ApplicationWrapper applicationWrapper,
+    @ApiOperation(
-                                  @PathParam("tenantDomain") String tenantDomain);
+            consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML,
+            httpMethod = "POST",
+            value = "Uninstalling an Application from a Device.",
+            notes = "Uninstall a selected application from a device.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Operation was successfully added to the queue."),
+                            @ApiResponse(code = 500, message = "Error occurred while saving the operation.") })
+    Response uninstallApplication(@ApiParam(name = "applicationWrapper", value = "Details about the application and" +
+                                                                                 " the users and roles it should be " +
+                                                                                 "uninstalled.",
+                                            required = true) ApplicationWrapper applicationWrapper,
+                                  @ApiParam(name = "tenantDomain", value = "Provide the tenant domain as the value for " +
+                                                                           "{tenantDomain}. The default tenant domain " +
+                                                                           "of WSO2 EMM is carbon.super.",
+                                            required = true) @PathParam("tenantDomain") String tenantDomain);
 }

components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java

@@ -18,8 +18,9 @@
 
 package org.wso2.carbon.device.mgt.jaxrs.api;
 
-import io.swagger.annotations.Api;
+import io.swagger.annotations.*;
 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.PolicyWrapper;
 import org.wso2.carbon.device.mgt.jaxrs.beans.PriorityUpdatedPolicyWrapper;
 
@@ -42,59 +43,195 @@ public interface Policy {
 
     @POST
     @Path("inactive-policy")
-    Response addPolicy(PolicyWrapper policyWrapper);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "POST",
+            value = "Adding a Policy.",
+            notes = "Add a policy using this REST API command. When adding a policy you will have the option of " +
+                    "saving the policy or saving and publishing the policy. Using the REST API command given below " +
+                    "you are able to save a created Policy and this policy will be in the inactive state")
+    @ApiResponses(value = { @ApiResponse(code = 201, message = "Created the policy."),
+                            @ApiResponse(code = 500, message = "Policy Management related error occurred when " +
+                                                               "adding the policy") })
+    Response addPolicy(@ApiParam(name = "policyWrapper", value = "Policy details related to the operation.",
+                                  required = true) PolicyWrapper policyWrapper);
 
     @POST
     @Path("active-policy")
-    Response addActivePolicy(PolicyWrapper policyWrapper);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "POST",
+            value = "Adding an Active Policy.",
+            notes = "Add a policy that is in the active state using the REST API command. When adding a policy you " +
+                    "will have the option of saving the policy or saving and publishing the policy. Using the REST " +
+                    "API command given below you are able to save and publish a created policy and this policy will " +
+                    "be in the active state.")
+    @ApiResponses(value = { @ApiResponse(code = 201, message = "Created the policy."),
+                            @ApiResponse(code = 500, message = "Policy Management related error occurred when " +
+                                                               "adding the policy") })
+    Response addActivePolicy(@ApiParam(name = "policyWrapper", value = "Policy details related to the operation.",
+                                       required = true) PolicyWrapper policyWrapper);
 
     @GET
     @Produces({ MediaType.APPLICATION_JSON})
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting Details of Policies.",
+            responseContainer = "List",
+            notes = "Retrieve the details of all the policies that you have created in WSO2 EMM.",
+            response = org.wso2.carbon.policy.mgt.common.Policy.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Fetched all policies."),
+                            @ApiResponse(code = 500, message = "Policy Management related error occurred when " +
+                                                               "fetching the policies.") })
     Response getAllPolicies();
 
     @GET
     @Produces({MediaType.APPLICATION_JSON})
     @Path("{id}")
-    Response getPolicy(@PathParam("id") int policyId);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting Details of a Policy.",
+            notes = "Retrieve the details of a selected policy in WSO2 EMM.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Fetched policy details."),
+                            @ApiResponse(code = 500, message = "Policy Management related error occurred when " +
+                                                               "fetching the policies.") })
+    Response getPolicy(@ApiParam(name = "id", value = "Policy ID value to identify a policy uniquely.",
+                                 required = true) @PathParam("id") int policyId);
 
     @GET
     @Path("count")
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting the Policy Count.",
+            notes = "Get the number of policies that are created in WSO2 EMM.",
+            response = Integer.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Fetched the policy count."),
+                            @ApiResponse(code = 500, message = "Error while Fetching the policy count.") })
     Response getPolicyCount();
 
     @PUT
     @Path("{id}")
-    Response updatePolicy(PolicyWrapper policyWrapper, @PathParam("id") int policyId);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Updating a Policy.",
+            notes = "If you wish to make changes to an existing policy, you can do so by updating the policy using " +
+                    "this API")
+    @ApiResponses(value = { @ApiResponse(code = 201, message = "Policy has been updated successfully."),
+                            @ApiResponse(code = 500, message = "Policy Management related exception in policy " +
+                                                               "update") })
+    Response updatePolicy(@ApiParam(name = "policyWrapper", value = "Policy details related to the operation.",
+                                    required = true) PolicyWrapper policyWrapper,
+                          @ApiParam(name = "id", value = "Policy ID value to identify a policy uniquely.",
+                                    required = true) @PathParam("id") int policyId);
 
     @PUT
     @Path("priorities")
     @Consumes({MediaType.APPLICATION_JSON})
     @Produces({MediaType.APPLICATION_JSON})
-    Response updatePolicyPriorities(List<PriorityUpdatedPolicyWrapper> priorityUpdatedPolicies);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Updating the Policy Priority.",
+            notes = "If you wish to make changes to the existing policy priority order, " +
+                    "you can do so by updating the priority order using this API")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Policy Priorities successfully updated."),
+                            @ApiResponse(code = 400, message = "Policy priorities did not update."),
+                            @ApiResponse(code = 500, message = "Error in updating policy priorities.") })
+    Response updatePolicyPriorities(@ApiParam(name = "priorityUpdatedPolicies",
+                                              value = "List of policy update details..",
+                                              required = true) List<PriorityUpdatedPolicyWrapper> priorityUpdatedPolicies);
 
     @POST
     @Path("bulk-remove")
     @Consumes("application/json")
     @Produces("application/json")
-    Response bulkRemovePolicy(List<Integer> policyIds);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "POST",
+            value = "Removing Multiple Policies.",
+            notes = "In situations where you need to delete more than one policy you can do so using this API.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Policies have been successfully deleted."),
+                            @ApiResponse(code = 400, message = "Policy does not exist."),
+                            @ApiResponse(code = 500, message = "Error in deleting policies.") })
+    Response bulkRemovePolicy(@ApiParam(name = "policyIds", value = "Policy ID list to be deleted.",
+                                        required = true) List<Integer> policyIds);
 
     @PUT
     @Produces("application/json")
     @Path("activate")
-    Response activatePolicy(List<Integer> policyIds);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Activating Policies.",
+            notes = "Using the REST API command you are able to publish a policy in order to bring a policy that is " +
+                    "in the inactive state to the active state.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Policies have been successfully activated."),
+                            @ApiResponse(code = 500, message = "Error in activating policies.") })
+    Response activatePolicy(@ApiParam(name = "policyIds", value = "Policy ID list to be activated.",
+                                      required = true) List<Integer> policyIds);
 
     @PUT
     @Produces("application/json")
     @Path("inactivate")
-    Response inactivatePolicy(List<Integer> policyIds) throws MDMAPIException;
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Deactivating Policies.",
+            notes = "Using the REST API command you are able to unpublish a policy in order to bring a policy that " +
+                    "is in the active state to the inactive state.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Policies have been successfully deactivated."),
+                            @ApiResponse(code = 500, message = "Error in deactivating policies.") })
+    Response inactivatePolicy(@ApiParam(name = "policyIds", value = "Policy ID list to be deactivated.",
+                                        required = true) List<Integer> policyIds) throws MDMAPIException;
 
     @PUT
     @Produces("application/json")
     @Path("apply-changes")
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Applying Changes on Policies.",
+            notes = "Policies in the active state will be applied to new device that register with WSO2 EMM based on" +
+                    " the policy enforcement criteria . In a situation where you need to make changes to existing" +
+                    " policies (removing, activating, deactivating and updating) or add new policies, the existing" +
+                    " devices will not receive these changes immediately. Once all the required changes are made" +
+                    " you need to apply the changes to push the policy changes to the existing devices.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Changes have been successfully updated."),
+                            @ApiResponse(code = 500, message = "Error in updating policies.") })
     Response applyChanges();
 
     @GET
     @Path("start-task/{milliseconds}")
-    Response startTaskService(@PathParam("milliseconds") int monitoringFrequency);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Starting Policy Monitoring.",
+            notes = "WSO2 EMM monitors the devices to identify any devices that have not complied to an enforced " +
+                    "policy. The policy monitoring task begins at the point WSO2 EMM has a a published policy. " +
+                    "It will monitor the device based on the policy monitoring frequency that you define in " +
+                    "milliseconds.Using this REST API to start the policy monitoring task is optional as " +
+                    "WSO2 EMM uses an OSGI call to start the monitoring task")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Policy monitoring service started successfully."),
+                            @ApiResponse(code = 500, message = "Policy Management related exception when starting " +
+                                                               "monitoring service.") })
+    Response startTaskService(@ApiParam(name = "milliseconds", value = "Policy monitoring frequency in milliseconds.",
+                                        required = true) @PathParam("milliseconds") int monitoringFrequency);
 
     @GET
     @Path("update-task/{milliseconds}")
@@ -110,5 +247,19 @@ public interface Policy {
 
     @GET
     @Path("{type}/{id}/active-policy")
-    Response getDeviceActivePolicy(@PathParam("type") String type, @PathParam("id") String id);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting Policy Enforced Details of a Device.",
+            notes = "When a device registers with WSO2 EMM a policy is enforced on the device. Initially the EMM " +
+                    "filters the policies based on the Platform (device type), filters based on the device ownership" +
+                    " type , filters based on the user role or name and finally the policy is enforced on the device.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Fetched current policy."),
+                            @ApiResponse(code = 500, message = "Error occurred while getting the current policy.") })
+    Response getDeviceActivePolicy(@ApiParam(name = "type", value = "Define the device type as the value for {type}." +
+                                                                    " Example: ios, android, windows..",
+                                             required = true) @PathParam("type") String type,
+                                   @ApiParam(name = "id", value = "Define the device ID as the value for {id}.",
+                                             required = true) @PathParam("id") String id);
 }

components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java

@@ -18,8 +18,11 @@
 
 package org.wso2.carbon.device.mgt.jaxrs.api;
 
-import io.swagger.annotations.Api;
+import io.swagger.annotations.*;
+import org.wso2.carbon.device.mgt.common.app.mgt.Application;
+import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
 import org.wso2.carbon.device.mgt.jaxrs.beans.RoleWrapper;
+import org.wso2.carbon.user.mgt.common.UIPermissionNode;
 
 import javax.ws.rs.DELETE;
 import javax.ws.rs.GET;
@@ -41,46 +44,168 @@ public interface Role {
 
     @GET
     @Produces({ MediaType.APPLICATION_JSON})
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting the List of Roles.",
+            responseContainer = "List",
+            notes = "If you wish to get the details of all the roles in WSO2 EMM, you can do so using this REST API.",
+            response = String.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "List of available roles"),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") })
     Response getRoles();
 
     @GET
     @Path("{userStore}")
     @Produces({MediaType.APPLICATION_JSON})
-    Response getRoles(@PathParam("userStore") String userStore);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting the List of Roles in a User Store.",
+            responseContainer = "List",
+            notes = "If you wish to get the details of all the roles in WSO2 EMM, you can do so using this REST API.",
+            response = String.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "List of available roles"),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") })
+    Response getRoles(@ApiParam(name = "userStore", value = "Provide the name of the UserStore you wish to get the" +
+                                                            " details from ",
+                                 required = true) @PathParam("userStore") String userStore);
 
     @GET
     @Path("search")
     @Produces({MediaType.APPLICATION_JSON})
-    Response getMatchingRoles(@QueryParam("filter") String filter);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Searching for Roles via the Role Name.",
+            responseContainer = "List",
+            notes = "You will have many roles created within WSO2 EMM. As the admin you will need to confirm if a " +
+                    "given role exists in the EMM. In such situation you can search for the role by giving a " +
+                    "character or a few characters of the role name. The search will give you a list of roles that" +
+                    " have the name in the exact order of the characters you provided.",
+            response = String.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "List of matching roles"),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the matching role list" +
+                                                               ".") })
+    Response getMatchingRoles(@ApiParam(name = "filter", value = "Provide a character or a few characters in the" +
+                                                                 " role name.",
+                                        required = true) @QueryParam("filter") String filter);
 
     @GET
     @Path("permissions")
     @Produces({MediaType.APPLICATION_JSON})
-    Response getPermissions(@QueryParam("rolename") String roleName);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting Permission Details of a Role.",
+            notes = "In an organization an individual is associated a with set of responsibilities based on their " +
+                    "role. In WSO2 EMM you are able to configure permissions based on the responsibilities carried " +
+                    "out by a role. Therefore if you wish to retrieve the permission details of a role, you can do " +
+                    "so using this REST API.",
+            response = UIPermissionNode.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Permission details of a role"),
+                            @ApiResponse(code = 500, message = "Error occurred while fetching the permission " +
+                                                               "details of a role.") })
+    Response getPermissions(@ApiParam(name = "rolename", value = "Provide the name of the role you wish to get the " +
+                                                                  "permission details.",
+                                       required = true) @QueryParam("rolename") String roleName);
 
     @GET
     @Path("role")
     @Produces({MediaType.APPLICATION_JSON})
-    Response getRole(@QueryParam("rolename") String roleName);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting Details of a Role.",
+            notes = "If you wish to get the details of a role in WSO2 EMM, you can do so using this REST API.",
+            response = RoleWrapper.class)
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Details of a role."),
+                            @ApiResponse(code = 500, message = "Error occurred while retrieving the user role.") })
+    Response getRole(@ApiParam(name = "rolename", value = "Provide the name of the role you wish to get the " +
+                                                          "details.",
+                               required = true) @QueryParam("rolename") String roleName);
 
     @POST
     @Produces({MediaType.APPLICATION_JSON})
-    Response addRole(RoleWrapper roleWrapper);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "POST",
+            value = "Adding a Role.",
+            notes = "You are able to add a new role to WSO2 EMM using the REST API.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Added the role."),
+                            @ApiResponse(code = 500, message = "Error occurred while adding the user role.") })
+    Response addRole(@ApiParam(name = "roleWrapper", value = "Role and permission details.",
+                               required = true) RoleWrapper roleWrapper);
 
     @PUT
     @Produces({MediaType.APPLICATION_JSON})
-    Response updateRole(@QueryParam("rolename") String roleName, RoleWrapper roleWrapper);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Updating a Role.",
+            notes = "There will be situations where you will need to update the role details, such as the permissions" +
+                    " or the role name. In such situation you can update the role details.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Updated the role."),
+                            @ApiResponse(code = 500, message = "Error occurred while updating the user role details" +
+                                                               ".") })
+    Response updateRole(@ApiParam(name = "rolename", value = "Provide the name of the role you wish to update.",
+                                  required = true) @QueryParam("rolename") String roleName,
+                        @ApiParam(name = "roleWrapper", value = "Role and permission details.",
+                                  required = true) RoleWrapper roleWrapper);
 
     @DELETE
     @Produces({MediaType.APPLICATION_JSON})
-    Response deleteRole(@QueryParam("rolename") String roleName);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "DELETE",
+            value = "Deleting a Role.",
+            notes = "In a situation when your Organization identifies that a specific role is no longer required you " +
+                    "will need to remove the role details from WSO2 EMM.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Deleted the role."),
+                            @ApiResponse(code = 500, message = "Error occurred while deleting the user role details" +
+                                                               ".") })
+    Response deleteRole(@ApiParam(name = "rolename", value = "Provide the name of the role you wish to delete.",
+                                  required = true) @QueryParam("rolename") String roleName);
 
     @PUT
     @Path("users")
     @Produces({MediaType.APPLICATION_JSON})
-    Response updateUsers(@QueryParam("rolename") String roleName, List<String> userList);
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "PUT",
+            value = "Adding Users to a Role.",
+            notes = "Defining the users to a role at the point of creating a new role is optional, " +
+                    "therefore you are able to update the users that belong to a given role after you have created " +
+                    "a role using this REST API." +
+                    "Example: Your Organization hires 30 new engineers. Updating the role details for each user can " +
+                    "be cumbersome, therefore you can define all the new employees that belong to the engineering " +
+                    "role using this API.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Added Users to a Role."),
+                            @ApiResponse(code = 500, message = "Error occurred while saving the users of the role.") })
+    Response updateUsers(@ApiParam(name = "rolename", value = "Provide the name of the role you wish to update.",
+                                   required = true) @QueryParam("rolename") String roleName,
+                         @ApiParam(name = "userList", value = "Provide the names of the users you will to update.",
+                                   required = true) List<String> userList);
 
     @GET
     @Path("count")
+    @ApiOperation(
+            consumes = MediaType.APPLICATION_JSON,
+            produces = MediaType.APPLICATION_JSON,
+            httpMethod = "GET",
+            value = "Getting the Role Count.",
+            response = Integer.class,
+            notes = "Get the number of roles in WSO2 EMM.")
+    @ApiResponses(value = { @ApiResponse(code = 200, message = "Retrieved the role count."),
+                            @ApiResponse(code = 500, message = "Error occurred while retrieving the role count.") })
     Response getRoleCount();
 }

components/device-mgt/org.wso2.carbon.device.mgt.common/pom.xml

@@ -53,4 +53,12 @@
         </plugins>
     </build>
 
+    <dependencies>
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-annotations</artifactId>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
 </project>

components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/Feature.java

@@ -20,6 +20,7 @@ package org.wso2.carbon.device.mgt.common;
 import javax.xml.bind.annotation.XmlElement;
 import java.io.Serializable;
 import java.util.List;
+import io.swagger.annotations.*;
 
 public class Feature implements Serializable {