From 5597c752ac5ee688d768d4f269ab1398c5401ae7 Mon Sep 17 00:00:00 2001 From: inosh-perera Date: Thu, 12 May 2016 20:17:20 +0530 Subject: [PATCH] Adding sawgger annotations to admin Jax-rs apis. --- .../carbon/device/mgt/jaxrs/api/Feature.java | 19 +- .../device/mgt/jaxrs/api/Operation.java | 107 ++++++++++- .../carbon/device/mgt/jaxrs/api/Policy.java | 173 ++++++++++++++++-- .../carbon/device/mgt/jaxrs/api/Role.java | 143 ++++++++++++++- .../org.wso2.carbon.device.mgt.common/pom.xml | 8 + .../carbon/device/mgt/common/Feature.java | 1 + 6 files changed, 420 insertions(+), 31 deletions(-) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java index cafd085015a..42f23ae3b9c 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java +++ b/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); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java index 9c8f8547883..131eef9b2da 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java +++ b/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, - @QueryParam("start") int startIdx, @QueryParam("length") int length, + @ApiOperation( + 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, - @PathParam("tenantDomain") String tenantDomain); + @ApiOperation( + 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, - @PathParam("tenantDomain") String tenantDomain); + @ApiOperation( + 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); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java index 1eebbb0c695..e266e8ee944 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java +++ b/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 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 priorityUpdatedPolicies); @POST @Path("bulk-remove") @Consumes("application/json") @Produces("application/json") - Response bulkRemovePolicy(List 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 policyIds); @PUT @Produces("application/json") @Path("activate") - Response activatePolicy(List 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 policyIds); @PUT @Produces("application/json") @Path("inactivate") - Response inactivatePolicy(List 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 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); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java index c6f9a9a2cfd..abf48eb8e5f 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java +++ b/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 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 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(); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.common/pom.xml b/components/device-mgt/org.wso2.carbon.device.mgt.common/pom.xml index 94a50811c3b..645392c8487 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.common/pom.xml +++ b/components/device-mgt/org.wso2.carbon.device.mgt.common/pom.xml @@ -53,4 +53,12 @@ + + + io.swagger + swagger-annotations + provided + + + diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/Feature.java b/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/Feature.java index 375b8d45628..0519367fa53 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/Feature.java +++ b/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 {