Adding sawgger annotations to admin Jax-rs apis.

revert-70aa11f8
inosh-perera 9 years ago
parent cdb91924e2
commit 5597c752ac

@ -18,13 +18,14 @@
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.*;
import javax.ws.rs.Consumes; import javax.ws.rs.Consumes;
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.Produces; import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -43,6 +44,20 @@ public interface Feature {
*/ */
@GET @GET
@Path("/{type}") @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);
} }

@ -18,8 +18,11 @@
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.*;
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.context.DeviceOperationContext;
import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload;
import org.wso2.carbon.device.mgt.jaxrs.beans.ApplicationWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.ApplicationWrapper;
import javax.ws.rs.GET; import javax.ws.rs.GET;
@ -27,6 +30,7 @@ import javax.ws.rs.POST;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.PathParam; import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam; import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
/** /**
@ -41,13 +45,55 @@ public interface Operation {
@GET @GET
@Path("paginate/{type}/{id}") @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); @QueryParam("search") String search);
@GET @GET
@Path("{type}/{id}") @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 */ /* @deprecated */
@POST @POST
@ -55,15 +101,58 @@ public interface Operation {
@GET @GET
@Path("{type}/{id}/apps") @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 @POST
@Path("installApp/{tenantDomain}") @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 @POST
@Path("uninstallApp/{tenantDomain}") @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);
} }

@ -18,8 +18,9 @@
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.*;
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.PolicyWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.PolicyWrapper;
import org.wso2.carbon.device.mgt.jaxrs.beans.PriorityUpdatedPolicyWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.PriorityUpdatedPolicyWrapper;
@ -42,59 +43,195 @@ public interface Policy {
@POST @POST
@Path("inactive-policy") @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 @POST
@Path("active-policy") @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 @GET
@Produces({ MediaType.APPLICATION_JSON}) @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(); Response getAllPolicies();
@GET @GET
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
@Path("{id}") @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 @GET
@Path("count") @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(); Response getPolicyCount();
@PUT @PUT
@Path("{id}") @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 @PUT
@Path("priorities") @Path("priorities")
@Consumes({MediaType.APPLICATION_JSON}) @Consumes({MediaType.APPLICATION_JSON})
@Produces({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 @POST
@Path("bulk-remove") @Path("bulk-remove")
@Consumes("application/json") @Consumes("application/json")
@Produces("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 @PUT
@Produces("application/json") @Produces("application/json")
@Path("activate") @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 @PUT
@Produces("application/json") @Produces("application/json")
@Path("inactivate") @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 @PUT
@Produces("application/json") @Produces("application/json")
@Path("apply-changes") @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(); Response applyChanges();
@GET @GET
@Path("start-task/{milliseconds}") @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 @GET
@Path("update-task/{milliseconds}") @Path("update-task/{milliseconds}")
@ -110,5 +247,19 @@ public interface Policy {
@GET @GET
@Path("{type}/{id}/active-policy") @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);
} }

@ -18,8 +18,11 @@
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.*;
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.device.mgt.jaxrs.beans.RoleWrapper;
import org.wso2.carbon.user.mgt.common.UIPermissionNode;
import javax.ws.rs.DELETE; import javax.ws.rs.DELETE;
import javax.ws.rs.GET; import javax.ws.rs.GET;
@ -41,46 +44,168 @@ public interface Role {
@GET @GET
@Produces({ MediaType.APPLICATION_JSON}) @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(); Response getRoles();
@GET @GET
@Path("{userStore}") @Path("{userStore}")
@Produces({MediaType.APPLICATION_JSON}) @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 @GET
@Path("search") @Path("search")
@Produces({MediaType.APPLICATION_JSON}) @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 @GET
@Path("permissions") @Path("permissions")
@Produces({MediaType.APPLICATION_JSON}) @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 @GET
@Path("role") @Path("role")
@Produces({MediaType.APPLICATION_JSON}) @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 @POST
@Produces({MediaType.APPLICATION_JSON}) @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 @PUT
@Produces({MediaType.APPLICATION_JSON}) @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 @DELETE
@Produces({MediaType.APPLICATION_JSON}) @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 @PUT
@Path("users") @Path("users")
@Produces({MediaType.APPLICATION_JSON}) @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 @GET
@Path("count") @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(); Response getRoleCount();
} }

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

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

Loading…
Cancel
Save