From 0842dcb2bbb327e0e7a1b791875db1872d739a0b Mon Sep 17 00:00:00 2001 From: Shavindri Date: Tue, 11 Oct 2016 10:33:05 +0530 Subject: [PATCH] swagger annotations and definition update continued for device type, device, policy, role, user, group and user management. --- .../api/ActivityInfoProviderService.java | 59 +++-- .../service/api/DeviceManagementService.java | 243 +++++++++--------- .../api/DeviceTypeManagementService.java | 32 +-- .../api/NotificationManagementService.java | 35 +-- .../service/api/PolicyManagementService.java | 156 +++++------ .../service/api/RoleManagementService.java | 23 +- .../service/api/UserManagementService.java | 194 +++++++------- .../admin/DeviceManagementAdminService.java | 40 +-- .../admin/GroupManagementAdminService.java | 20 +- .../api/admin/UserManagementAdminService.java | 16 +- 10 files changed, 441 insertions(+), 377 deletions(-) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java index d048ea75fda..e0f76027773 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java @@ -47,14 +47,14 @@ public interface ActivityInfoProviderService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Retrieve details of a particular activity.", - notes = "This will return information of a particular activity i.e. meta information of an operation, " + - "etc; including the responses from the devices.", + value = "Getting Details of an Activity", + notes = "Retrieve the details of a specific activity/operation, such as the meta information of an operation, " + + "including the responses from the devices.", tags = "Activity Info Provider") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Activity details are successfully fetched", + message = "OK. \n Successfully fetched the activity details.", response = Activity.class, responseHeaders = { @ResponseHeader( @@ -66,13 +66,12 @@ public interface ActivityInfoProviderService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of " + - "the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", @@ -82,28 +81,31 @@ public interface ActivityInfoProviderService { message = "Unauthorized. \n Unauthorized request."), @ApiResponse( code = 404, - message = "Not Found. \n No activity is found under the provided id.", + message = "Not Found. \n No activity found with the given ID.", response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported"), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching activity data.", + message = "Internal Server Error. \n Server error occurred while fetching the activity data.", response = ErrorResponse.class) }) @Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view") Response getActivity( @ApiParam( name = "id", - value = "Activity id of the operation/activity to be retrieved.", - required = true) + value = "Activity id of the operation/activity.", + required = true, + defaultValue = "ACTIVITY_1") @PathParam("id") @Size(max = 45) String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time\n." + + "Provide the value in the Java Date Format: EEE, d MMM yyyy HH:mm:ss Z\n." + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -112,14 +114,13 @@ public interface ActivityInfoProviderService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Retrieve details of a particular activity.", - notes = "This will return information of a particular activities i.e. meta information of operations, " + - "etc; including the responses from the devices which happened after given time.", + value = "Getting Activity Details", + notes = "Get the details of the operations/activities executed by the server on the devices registered with WSO2 EMM, during a defined time period.", tags = "Activity Info Provider") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Activity details are successfully fetched", + message = "OK. \n Successfully fetched the activity details.", response = ActivityList.class, responseHeaders = { @ResponseHeader( @@ -131,13 +132,12 @@ public interface ActivityInfoProviderService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of " + - "the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 401, message = "Unauthorized. \n Unauthorized request."), @@ -150,30 +150,35 @@ public interface ActivityInfoProviderService { message = "Not Acceptable.\n The requested media type is not supported"), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching activity data.", + message = "Internal Server Error. \n Server error occurred while fetching the activity data.", response = ErrorResponse.class) }) @Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view") Response getActivities( @ApiParam( name = "since", - value = "Validates if the requested variant has not been modified since the time specified, this " + - "should be provided in unix format in seconds.", + value = "Checks if the requested variant was created since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @QueryParam("since") String since, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many activity details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time\n." + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n." + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java index b185bd368d3..fbb751dacd6 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java @@ -52,8 +52,8 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the list of devices enrolled with the system.", - notes = "Returns all devices enrolled with the system.", + value = "Getting Details of Registered Devices", + notes = "Provides details of all the devices enrolled with WSO2 EMM.", tags = "Device Management") @ApiResponses(value = { @ApiResponse(code = 200, message = "OK. \n Successfully fetched the list of devices.", @@ -68,25 +68,23 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of " + - "the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 400, - message = "The incoming request has more than one selection criteria defined through query" + - " parameters.", + message = "The incoming request has more than one selection criteria defined via the query parameters.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "No device is currently enrolled with the server.", + message = "The search criteria did not match any device registered with the server.", response = ErrorResponse.class), @ApiResponse( code = 406, - message = "Not Acceptable.\n The requested media type is not supported"), + message = "Not Acceptable.\n The requested media type is not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n Server error occurred while fetching the device list.", @@ -96,7 +94,7 @@ public interface DeviceManagementService { Response getDevices( @ApiParam( name = "name", - value = "The device name, such as shamu, bullhead or angler.", + value = "The device name, such as shamu, bullhead or angler Nexus device names. ", required = false) @Size(max = 45) String name, @@ -109,47 +107,55 @@ public interface DeviceManagementService { String type, @ApiParam( name = "user", - value = "Username of owner of the devices.", + value = "The username of the owner of the device.", required = false) @QueryParam("user") String user, @ApiParam( name = "ownership", allowableValues = "BYOD, COPE", - value = "Ownership of the devices to be fetched registered under.", + value = "Provide the ownership status of the device. The following values can be assigned:\n" + + "- BYOD: Bring Your Own Device\n" + + "- COPE: Corporate-Owned, Personally-Enabled", required = false) @QueryParam("ownership") @Size(max = 45) String ownership, @ApiParam( name = "status", - value = "Enrollment status of devices to be fetched.", + value = "Provide the device status details, such as active or inactive.", required = false) @QueryParam("status") @Size(max = 45) String status, @ApiParam( name = "since", - value = "Last modified timestamp", + value = "Checks if the requested variant was created since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @QueryParam("since") String since, @ApiParam( name = "If-Modified-Since", - value = "Timestamp of the last modified date", + value = "Checks if the requested variant was modified, since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String timestamp, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many device details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @@ -159,14 +165,14 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get information of the requested device.", - notes = "Returns information of the requested device.", + value = "Getting Details of a Device", + notes = "Get the details of a device by specifying the device type and device identifier.", tags = "Device Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n Successfully fetched information of the device.", + message = "OK. \n Successfully fetched the details of the device.", response = Device.class, responseHeaders = { @ResponseHeader( @@ -178,25 +184,24 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. Empty body because the client already has the latest " + - "version of the requested resource."), + message = "Not Modified. Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n No device is found under the provided type and id.", + message = "Not Found. \n A device with the specified device type and id was not found.", response = ErrorResponse.class), @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while retrieving information requested device.", + "Server error occurred while retrieving the device details.", response = ErrorResponse.class) }) @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @@ -204,20 +209,23 @@ public interface DeviceManagementService { @ApiParam( name = "type", value = "The device type, such as ios, android or windows.", - required = true) + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @ApiParam( name = "id", - value = "The device identifier of the device.", + value = "The device identifier of the device you want ot get details.", required = true) @PathParam("id") @Size(max = 45) String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -228,8 +236,8 @@ public interface DeviceManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, 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. " + + value = "Getting Feature Details of a Device", + notes = "WSO2 EMM features enable you to carry out many operations based on the 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.", tags = "Device Management") @@ -237,7 +245,7 @@ public interface DeviceManagementService { value = { @ApiResponse( code = 200, - message = "OK. \n List of features of the device is returned", + message = "OK. \n Successfully fetched the list of features.", response = Feature.class, responseContainer = "List", responseHeaders = { @@ -250,12 +258,12 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 303, message = "See Other. \n " + - "Source can be retrieved from the URL specified at the Location header.", + "The source can be retrieved from the URL specified in the location header.", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -270,7 +278,7 @@ public interface DeviceManagementService { response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Device of which the feature list is requested, is not found.", + message = "Not Found. \n The specified device can not be found.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -278,7 +286,7 @@ public interface DeviceManagementService { @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while retrieving feature list of the device.", + "Server error occurred while retrieving the feature list for the device platform.", response = ErrorResponse.class) }) @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @@ -286,20 +294,24 @@ public interface DeviceManagementService { @ApiParam( name = "type", value = "The device type, such as ios, android or windows.", - required = true) + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @ApiParam( name = "id", - value = "The device identifier of the device.", + value = "The device identifier of the device.\n" + + "INFO: Make sure to add the ID of a device that is already registered with WSO2 EMM.", required = true) @PathParam("id") @Size(max = 45) String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -310,15 +322,14 @@ public interface DeviceManagementService { produces = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Advanced search for devices.", - notes = "Carry out an advanced search of devices.", + value = "Advanced Search for Devices", + notes = "Search for devices by filtering the search result through the specified search terms.", tags = "Device Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n Device list searched for has successfully been retrieved. Location header " + - "contains URL of newly enrolled device", + message = "OK. \n Successfully retrieved the device information.", response = DeviceList.class, responseHeaders = { @ResponseHeader( @@ -330,50 +341,51 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified. \n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 304, message = "Not Modified. \n " + - "Empty body because the client already has the latest version of the requested resource."), + "Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Acceptable.\n TIt is likely that no device is found upon the " + - "provided filters", + message = "Not Acceptable.\n The existing device did not match the values specified in the device search.", response = ErrorResponse.class), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported"), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format."), + message = "Unsupported media type. \n The format of the requested entity was not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while enrolling the device.", + "Server error occurred while getting the device details.", response = ErrorResponse.class) }) @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") Response searchDevices( @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many activity details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit, @ApiParam( name = "searchContext", - value = "List of device properties as search conditions.", + value = "The properties to advanced search devices.", required = true) SearchContext searchContext); @@ -382,14 +394,14 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting installed application details of a device.", - notes = "Get the list of applications that a device has subscribed.", + value = "Getting Installed Application Details of a Device", + notes = "Get the list of applications subscribed to by a device.", tags = "Device Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n List of applications installed into the device is returned", + message = "OK. \n Successfully fetched the list of applications.", response = Application.class, responseContainer = "List", responseHeaders = { @@ -402,13 +414,12 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the " - + "last time.\n" + + description = "Date and time the resource was last modified\n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 303, message = "See Other. \n " + - "Source can be retrieved from the URL specified at the Location header.", + "The source can be retrieved from the URL specified in the location header.\n", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -416,16 +427,14 @@ public interface DeviceManagementService { @ApiResponse( code = 304, message = "Not Modified. \n " + - "Empty body because the client already has the latest version of the " - + "requested resource."), + "Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Device of which the application list is requested, is " - + "not found.", + message = "Not Found. \n The specified device does not exist.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -433,14 +442,16 @@ public interface DeviceManagementService { @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while retrieving installed application list of the device.", + "Server error occurred while retrieving the list of installed application on the device.", response = ErrorResponse.class) }) @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") Response getInstalledApplications( @ApiParam( name = "type", - value = "The device type, such as ios, android or windows.", required = true) + value = "The device type, such as ios, android or windows.", + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @@ -453,20 +464,24 @@ public interface DeviceManagementService { String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many application details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @@ -476,16 +491,14 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting paginated details for operations on a device.", - notes = "You will carry out many operations on a device. In a situation where you wish to view " - + "the all the operations carried out on a device it is not feasible to show all the " - + "details on one page therefore the details are paginated.", + value = "Getting Device Operation Details", + notes = "Get the details of operations carried out on a selected device.", tags = "Device Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n List of operations scheduled for the device is returned", + message = "OK. \n Successfully fetched the list of operations scheduled for the device.", response = Operation.class, responseContainer = "List", responseHeaders = { @@ -498,13 +511,12 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the " - + "last time.\n" + + description = "Date and time the resource was last modified" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 303, message = "See Other. \n " + - "Source can be retrieved from the URL specified at the Location header.", + "The source can be retrieved from the URL specified in the location header.\n", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -512,16 +524,14 @@ public interface DeviceManagementService { @ApiResponse( code = 304, message = "Not Modified. \n " + - "Empty body because the client already has the latest version of the " - + "requested resource."), + "Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Device of which the operation list is requested, is not " - + "found.", + message = "Not Found. \n The specified device does not exist.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -529,7 +539,7 @@ public interface DeviceManagementService { @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while retrieving operation list scheduled for the device.", + "Server error occurred while retrieving the operation list scheduled for the device.", response = ErrorResponse.class) }) @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @@ -537,34 +547,39 @@ public interface DeviceManagementService { @ApiParam( name = "type", value = "The device type, such as ios, android or windows.", - required = true) + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @ApiParam( name = "id", - value = "The device identifier of the device.", + value = "The device identifier of the device you wish to get details.\n" + + "INFO: Make sure to add the ID of a device that is already registered with WSO2 EMM.", required = true) @PathParam("id") @Size(max = 45) String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time " - + "specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many activity details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @@ -573,17 +588,16 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the effective policy calculated for 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.", + value = "Get the details of the policy that is enforced on a device.", + notes = "A policy is enforced on all the devices that registers with WSO2 EMM." + + "WSO2 EMM filters the policies based on the device platform (device type)," + + "the device ownership type, the user role or name and finally, the policy that matches these filters will be enforced on the device.", tags = "Device Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n Effective policy calculated for the device is returned", + message = "OK. \n Successfully returned the details of the policy enforced on the device.", response = Policy.class, responseHeaders = { @ResponseHeader( @@ -595,13 +609,12 @@ public interface DeviceManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the " - + "last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 303, message = "See Other. \n " + - "Source can be retrieved from the URL specified at the Location header.", + "The source can be retrieved from the URL specified in the location header.\n", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -609,16 +622,14 @@ public interface DeviceManagementService { @ApiResponse( code = 304, message = "Not Modified. \n " + - "Empty body because the client already has the latest version of the " - + "requested resource."), + "Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Device of which the effective policy is requested, is " - + "not found.", + message = "Not Found. \n The specified device does not exist.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -626,7 +637,7 @@ public interface DeviceManagementService { @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while retrieving the effective policy calculated for the device.", + "Server error occurred while retrieving the policy details that is enforced on the device.", response = ErrorResponse.class) } ) @@ -635,21 +646,23 @@ public interface DeviceManagementService { @ApiParam( name = "type", value = "The device type, such as ios, android or windows.", - required = true) + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @ApiParam( name = "id", - value = "Device Identifier", + value = "The device identifier.", required = true) @PathParam("id") @Size(max = 45) String id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time " - + "specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -660,11 +673,9 @@ public interface DeviceManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the effective policy calculated for 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.", + value = "Getting Policy Compliance Details of a Device", + notes = "A policy is enforced on the devices that register with WSO2 EMM. " + + "The server checks if the settings in the device comply with the policy that is enforced on the device using this REST API.", tags = "Device Management") @ApiResponses( value = { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java index 8aa54a5378e..ef79662b033 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java @@ -53,8 +53,8 @@ public interface DeviceTypeManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the list of device types registered.", - notes = "Retrieves the list of device types of which the devices intended to be managed.", + value = "Getting the Supported Device Platforms", + notes = "Get the list of device platforms supported by WSO2 EMM.", tags = "Device Type Management") @ApiResponses( value = { @@ -73,16 +73,14 @@ public interface DeviceTypeManagementService { @ResponseHeader( name = "Last-Modified", description = - "Date and time the resource has been modified the last time.\n" + + "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), } ), @ApiResponse( code = 304, message = - "Not Modified. \n Empty body because the client has already the latest version of" + - " " + - "the requested resource."), + "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported"), @@ -97,7 +95,9 @@ public interface DeviceTypeManagementService { Response getDeviceTypes( @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -106,8 +106,9 @@ public interface DeviceTypeManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the list of features for a give device type.", - notes = "Retrieves the list of features of a given device type.", + value = "Get Feature Details of a Device Type", + notes = "The features in WSO2 EMM enables 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.", tags = "Device Type Management") @ApiResponses( value = { @@ -126,16 +127,14 @@ public interface DeviceTypeManagementService { @ResponseHeader( name = "Last-Modified", description = - "Date and time the resource has been modified the last time.\n" + + "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), } ), @ApiResponse( code = 304, message = - "Not Modified. \n Empty body because the client has already the latest version of" + - " " + - "the requested resource."), + "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported"), @@ -151,13 +150,16 @@ public interface DeviceTypeManagementService { @ApiParam( name = "type", value = "The device type, such as ios, android or windows.", - required = true) + required = true, + allowableValues = "android, ios, windows") @PathParam("type") @Size(max = 45) String type, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/NotificationManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/NotificationManagementService.java index e0a2a3b1f72..00a1b8eb156 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/NotificationManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/NotificationManagementService.java @@ -47,9 +47,8 @@ public interface NotificationManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting all device notification details.", - notes = "Get the details of all notifications that were pushed to the device in WSO2 EMM using " - + "this REST API", + value = "Getting All Device Notification Details", + notes = "Get the details of all the notifications that were pushed to the devices registered with WSO2 EMM using this REST API.", tags = "Device Notification Management") @ApiResponses( value = { @@ -67,20 +66,20 @@ public interface NotificationManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, - message = "Bad Request. \n Invalid notification status type " + - "received. Valid status types are NEW | CHECKED", + message = "Bad Request. \n Invalid notification status type received. \n" + + "Valid status types are NEW | CHECKED", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n No notification is available to be retrieved.", + message = "Not Found. \n There are no notification.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -95,26 +94,30 @@ public interface NotificationManagementService { Response getNotifications( @ApiParam( name = "status", - value = "Status of the notification.", + value = "The status of the notification. Provide any of the following values: \n" + + " - NEW: Will keep the message in the unread state.\n" + + " - CHECKED: Will keep the message in the read state.", allowableValues = "NEW, CHECKED", required = false) @QueryParam("status") @Size(max = 45) String status, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", + value = "The starting pagination index for the complete list of qualified items.", required = false) @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", + value = "Provide how many notification details you require from the starting pagination index/offset.", required = false) @QueryParam("limit") int limit); @@ -137,7 +140,8 @@ public interface NotificationManagementService { @ApiResponse( code = 200, message = "Notification updated successfully. But the retrial of the updated " - + "notification failed."), + + "notification failed.", + response = Notification.class), @ApiResponse( code = 500, message = "Error occurred while updating notification status.") @@ -147,8 +151,9 @@ public interface NotificationManagementService { Response updateNotificationStatus( @ApiParam( name = "id", - value = "Notification ID.", - required = true) + value = "The notification ID.", + required = true, + defaultValue = "1") @PathParam("id") @Max(45) int id); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/PolicyManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/PolicyManagementService.java index 70edb9126f9..65c7f093b45 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/PolicyManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/PolicyManagementService.java @@ -40,8 +40,7 @@ import java.util.List; @API(name = "Device Policy Management", version = "1.0.0", context = "/api/device-mgt/v1.0/policies", tags = {"devicemgt_admin"}) -@Api(value = "Device Policy Management", description = "This API carries all the necessary functionalities " + - "around device policy management") +@Api(value = "Device Policy Management", description = "This API includes the functionality around device policy management") @Path("/policies") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @@ -52,14 +51,15 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Add a new policy.", - notes = "This particular resource can be used to add a new policy, which will be created in in-active state.", + 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 this REST API you are able to save a created Policy and this policy will be in the inactive state.", tags = "Device Policy Management") @ApiResponses( value = { @ApiResponse( code = 201, - message = "Created. \n Policy has successfully been created", + message = "Created. \n Successfully created the policy.", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -73,13 +73,13 @@ public interface PolicyManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.") } ), @ApiResponse( code = 303, - message = "See Other. \n Source can be retrieved from the URL specified at the Location header.", + message = "See Other. \n he source can be retrieved from the URL specified in the location header", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -90,11 +90,11 @@ public interface PolicyManagementService { response = ErrorResponse.class), @ApiResponse( code = 401, - message = "Not Found. \n Current logged in user is not authorized to add policies.", + message = "Not Found. \n The user that is currently logged in is not authorized to add policies.", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format."), + message = "Unsupported media type. \n The format of the requested entity was not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n " + @@ -105,17 +105,18 @@ public interface PolicyManagementService { Response addPolicy( @ApiParam( name = "policy", - value = "Policy details related to the operation.", - required = true) + value = "The properties required to add a new policy.", + required = true, + defaultValue = "{\"policyName\":\"test\",\"description\":\"test desc\",\"compliance\":\"ENFORCE\",\"ownershipType\":\"string\",\"active\":false,\"profile\":{\"profileId\":0,\"profileName\":\"string\",\"tenantId\":0,\"deviceType\":\"string\",\"createdDate\":\"2016-10-07T04:50:01.931Z\",\"updatedDate\":\"2016-10-07T04:50:01.931Z\",\"profileFeaturesList\":[{\"id\":0,\"featureCode\":\"string\",\"profileId\":0,\"deviceType\":\"string\",\"content\":{}}]},\"roles\":[\"string\"],\"deviceIdentifiers\":[{\"id\":\"string\",\"type\":\"string\"}],\"users\":[\"string\"]}") @Valid PolicyWrapper policy); @GET @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get details of policies.", + value = "Getting Details of Policies", responseContainer = "List", - notes = "Retrieve the details of all the policies that have been created in EMM.", + notes = "Retrieve the details of all the policies in WSO2 EMM.", response = Policy.class, tags = "Device Policy Management") @ApiResponses( @@ -135,13 +136,13 @@ public interface PolicyManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), } ), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", @@ -151,28 +152,31 @@ public interface PolicyManagementService { message = "Not Acceptable.\n The requested media type is not supported"), @ApiResponse( code = 500, - message = ("Internal Server Error. \n Server error occurred while fetching " + - "policies."), + message = ("Internal Server Error. \n Server error occurred while fetching the policies."), response = ErrorResponse.class) }) @Permission(name = "View policies", permission = "/device-mgt/policies/view") Response getPolicies( @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", value = "Maximum size of resource array to return.", - required = false) + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @@ -181,8 +185,8 @@ public interface PolicyManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get details of a policy.", - notes = "Retrieve the details of a given policy that has been created in EMM.", + value = "Getting Details of a Policy", + notes = "Retrieve the details of a policy that is in WSO2 EMM.", response = Policy.class, tags = "Device Policy Management") @ApiResponses( @@ -201,20 +205,20 @@ public interface PolicyManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), } ), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 404, - message = "Not Found. \n No policy is found with the given id.", + message = "Not Found. \n A specified policy was not found.", response = ErrorResponse.class), @ApiResponse( code = 406, - message = "Not Acceptable.\n The requested media type is not supported"), + message = "Not Acceptable.\n The requested media type is not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n Server error occurred while fetching the " + @@ -225,13 +229,16 @@ public interface PolicyManagementService { Response getPolicy( @ApiParam( name = "id", - value = "Policy identifier", - required = true) + value = "The policy identifier.", + required = true, + defaultValue = "") @PathParam("id") int id, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -242,15 +249,14 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Update a policy.", - notes = "If you wish to make changes to an existing policy, that can be done by updating the policy using " + - "this resource.", + value = "Updating a Policy", + notes = "Make changes to an existing policy by updating the policy using this resource.", tags = "Device Policy Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n Policy has been updated successfully", + message = "OK. \n Successfully updated the policy.", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -264,7 +270,7 @@ public interface PolicyManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.") } ), @@ -274,11 +280,11 @@ public interface PolicyManagementService { response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format."), + message = "Unsupported media type. \n The format of the requested entity was not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n " + @@ -289,13 +295,14 @@ public interface PolicyManagementService { Response updatePolicy( @ApiParam( name = "id", - value = "The device identifier of the device.", - required = true) + value = "The policy ID.", + required = true, + defaultValue = "1") @PathParam("id") int id, @ApiParam( name = "policy", - value = "Policy details related to the operation.", + value = "Update the required property details.", required = true) @Valid PolicyWrapper policy); @@ -305,38 +312,39 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Remove multiple policies.", - notes = "In situations where you need to delete more than one policy you can do so using this API.", + value = "Removing Multiple Policies", + notes = "Delete one or more than one policy using this API.", tags = "Device Policy Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "OK. \n Policies have successfully been removed"), + message = "OK. \n Successfully removed the policy."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not " + message = "Unsupported media type. \n The format of the requested entity was not supported.\n " + "supported format."), @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while bulk removing policies.", + "Server error occurred whilst bulk removing policies.", response = ErrorResponse.class) }) @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") Response removePolicies( @ApiParam( name = "policyIds", - value = "Policy id list to be deleted.", - required = true) + value = "The list of policy IDs to be removed.", + required = true, + defaultValue = "[1]") List policyIds); @POST @@ -344,35 +352,35 @@ public interface PolicyManagementService { @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.", + httpMethod = "POST", + value = "Activating Policies", + notes = "Publish a policy using this API to bring a policy that is in the inactive state to the active state.", tags = "Device Policy Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "Policies have been successfully activated."), + message = "Successfully activated the policy."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource does not exist.", + message = "Not Found. \n The specified resource/s does not exist.", response = ErrorResponse.class), @ApiResponse( code = 500, - message = "ErrorResponse in activating policies.", + message = "Sever error whilst activating the policies.", response = ErrorResponse.class) }) @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") Response activatePolicies( @ApiParam( name = "policyIds", - value = "Policy ID list to be activated.", - required = true) + value = "The list of the policy IDs to be activated", + required = true, + defaultValue = "[1]") List policyIds); @POST @@ -380,23 +388,22 @@ public interface PolicyManagementService { @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.", + httpMethod = "POST", + value = "Deactivating Policies", + notes = "Unpublish a policy using this API to bring a policy that is in the active state to the inactive state.", tags = "Device Policy Management") @ApiResponses( value = { @ApiResponse( code = 200, - message = "Policies have been successfully deactivated."), + message = "Successfully deactivated the policy."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 500, @@ -407,8 +414,9 @@ public interface PolicyManagementService { Response deactivatePolicies( @ApiParam( name = "policyIds", - value = "Policy ID list to be deactivated.", - required = true) + value = "The list of Policy IDs that needs to be deactivated.", + required = true, + defaultValue = "[1]") List policyIds); @PUT @@ -418,7 +426,7 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Applying Changes on Policies.", + 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" + @@ -430,7 +438,7 @@ public interface PolicyManagementService { value = { @ApiResponse( code = 200, - message = "Changes have been successfully updated."), + message = "Successfully updated the EMM server with the policy changes."), @ApiResponse( code = 500, message = "ErrorResponse in deactivating policies.", @@ -446,23 +454,22 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Prioritizing policies.", - notes = "If you wish to make changes to the existing policy priority order, you can do so by " - + "updating the priority order using this end-point", + value = "Updating the Policy Priorities", + notes = "Make changes to the existing policy priority order by updating the priority order using this API.", tags = "Device Policy Management" ) @ApiResponses( value = { @ApiResponse( code = 200, - message = "Policy Priorities successfully updated."), + message = "Successfully updated the policy priority order."), @ApiResponse( code = 400, - message = "Policy priorities did not update. Bad Request.", + message = "Bad Request. Did not update the policy priority order.", response = ErrorResponse.class), @ApiResponse( code = 500, - message = "Exception in updating policy priorities.", + message = "Exception in updating the policy priorities.", response = ErrorResponse.class) }) @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") @@ -470,7 +477,8 @@ public interface PolicyManagementService { @ApiParam( name = "priorityUpdatedPolicies", value = "List of policies with priorities", - required = true) + required = true, + defaultValue = "[{id:1,priority:2}]") List priorityUpdatedPolicies); diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/RoleManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/RoleManagementService.java index 0a9b5e80569..d6e9f5033c5 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/RoleManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/RoleManagementService.java @@ -99,13 +99,13 @@ public interface RoleManagementService { @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "The starting pagination index for the complete list qualified items.", + value = "The starting pagination index for the complete list of qualified items.", required = false, defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Provide how many roles details you require from the starting pagination index/offset.", + value = "Provide how many role details you require from the starting pagination index/offset.", required = false, defaultValue = "5") @QueryParam("limit") int limit); @@ -348,11 +348,13 @@ public interface RoleManagementService { name = "roleName", value = "The name of the role.", required = true, - defaultValue = "engineer") + defaultValue = "admin") @PathParam("roleName") String roleName, @ApiParam( name = "role", - value = "The properties required to update a role.", + value = "The properties required to update a role.\n" + + "NOTE: Don't change the role and the permissions of the admin user. " + + "If you want to try out this API by updating all the properties, create a new role and update the properties accordingly.", required = true) RoleInfo role); @DELETE @@ -384,9 +386,9 @@ public interface RoleManagementService { Response deleteRole( @ApiParam( name = "roleName", - value = "The name of the role that needs to de deleted.", - required = true, - defaultValue = "engineer") + value = "The name of the role that needs to de deleted.\n" + + "NOTE: Don't delete the admin role", + required = true) @PathParam("roleName") String roleName); @PUT @@ -443,15 +445,16 @@ public interface RoleManagementService { Response updateUsersOfRole( @ApiParam( name = "roleName", - value = "Name of the role.", - required = true) + value = "The name of the role.", + required = true, + defaultValue = "admin") @PathParam("roleName") String roleName, @ApiParam( name = "users", value = "Define the users that belong to the role.\n" + "Multiple users can be added to a role by using comma separated values. ", required = true, - defaultValue = "[jim]" + defaultValue = "[admin]" ) List users); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/UserManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/UserManagementService.java index 1a5e3440efc..1443311e241 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/UserManagementService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/UserManagementService.java @@ -42,14 +42,14 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Add a user.", - notes = "A new user can be added to the user management system via this resource", + value = "Adding a User", + notes = "WSO2 EMM supports user management. Add a new user to the WSO2 EMM user management system via this REST API", tags = "User Management") @ApiResponses( value = { @ApiResponse( code = 201, - message = "Created. \n User has successfully been created", + message = "Created. \n Successfully created the user.", responseHeaders = { @ResponseHeader( name = "Content-Location", @@ -63,7 +63,7 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 400, @@ -87,7 +87,8 @@ public interface UserManagementService { Response addUser( @ApiParam( name = "user", - value = "Information of the user to be added", + value = "Provide the property details to add a new user.\n" + + "Double click the example value and click try out. ", required = true) UserInfo user); @GET @@ -95,15 +96,14 @@ public interface UserManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting details of a user.", - notes = "If you wish to get the details of a specific user that is registered with EMM," - + " you can do so using the REST API.", + value = "Getting Details of a User", + notes = "Get the details of a user registered with WSO2 EMM using the REST API.", response = BasicUserInfo.class, tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Successfully fetched the requested role.", + message = "OK. \n Successfully fetched the details of the specified user.", response = BasicUserInfo.class, responseHeaders = { @ResponseHeader( @@ -115,15 +115,15 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 404, - message = "Not Found. \n Resource does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -132,24 +132,27 @@ public interface UserManagementService { @ApiResponse( code = 500, message = "Internal Server ErrorResponse. \n Server error occurred while" + - " fetching the requested user.", + " fetching the ruser details.", response = ErrorResponse.class) }) @Permission(name = "View Users", permission = "/device-mgt/users/view") Response getUser( @ApiParam( name = "username", - value = "Username of the user to be fetched.", - required = true) + value = "Provide the username of the user.", + required = true, + defaultValue = "admin") @PathParam("username") String username, @ApiParam( name = "domain", - value = "Domain name of the user store.", + value = "The domain name of the user store.", required = false) @QueryParam("domain") String domain, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time.\n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince); @@ -159,14 +162,14 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Update details of a user", + value = "Updating Details of a User", notes = "There will be situations where you will want to update the user details. In such " + "situation you can update the user details using this REST API.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n User has been updated successfully", + message = "OK. \n Successfully updated the details of the specified user.", responseHeaders = { @ResponseHeader( name = "Content-Type", @@ -177,7 +180,7 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests.")}), @ApiResponse( code = 400, @@ -185,11 +188,11 @@ public interface UserManagementService { response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format.", + message = "Unsupported media type. \n The format of the requested entity was not supported.", response = ErrorResponse.class), @ApiResponse( code = 500, @@ -201,34 +204,35 @@ public interface UserManagementService { Response updateUser( @ApiParam( name = "username", - value = "Username of the user to be updated.", - required = true) + value = "The username of the user.", + required = true, + defaultValue = "admin") @PathParam("username") String username, @ApiParam( name = "domain", - value = "Domain name of the user store.", + value = "The domain name of the user store.", required = false) @QueryParam("domain") String domain, @ApiParam( name = "userData", - value = "User related details.", + value = "Update the user details.\n" + + "NOTE: Do not change the admin username, password and roles when trying out this API.", required = true) UserInfo userData); @DELETE @Path("/{username}") @ApiOperation( httpMethod = "DELETE", - value = "Deleting a user.", - notes = "In a situation where an employee leaves the organization you will need to remove the" - + " user details from EMM. In such situations you can use this REST API to remove a user.", + value = "Deleting a User", + notes = "When an employee leaves the organization, you can remove the user details from WSO2 EMM using this REST API.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n User has successfully been removed"), + message = "OK. \n Successfully removed the user from WSO2 EMM."), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 500, @@ -239,11 +243,16 @@ public interface UserManagementService { }) @Permission(name = "Manage Users", permission = "/device-mgt/users/manage") Response removeUser( - @ApiParam(name = "username", value = "Username of the user to be deleted.", required = true) + @ApiParam( + name = "username", + value = "Username of the user to be deleted.\n" + + "INFO: If you want to try out this API, make sure to create a new user and then remove that user. Do not remove the admin user.", + required = true, + defaultValue = "[Create a new user named Jim, and then try out this API.]") @PathParam("username") String username, @ApiParam( name = "domain", - value = "Domain name of the user store.", + value = "The domain name of the user store.", required = false) @QueryParam("domain") String domain); @@ -252,14 +261,13 @@ public interface UserManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get the role list of a user.", - notes = "A user can be assigned to one or more role in EMM. Using this REST API you are " - + "able to get the role/roles a user is assigned to.", + value = "Getting the Role Details of a User", + notes = "A user can be assigned to one or more role in EMM. Using this REST API you can get the role/roles a user is assigned to.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Successfully fetched the role list assigned to the user.", + message = "OK. \n Successfully fetched the list of roles the specified user is assigned to.", response = RoleList.class, responseHeaders = { @ResponseHeader( @@ -271,15 +279,15 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.\n", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -287,17 +295,21 @@ public interface UserManagementService { response = ErrorResponse.class), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching the role list" + - " assigned to the user.", + message = "Internal Server Error. \n Server error occurred while fetching the list of roles" + + " assigned to the specified user.", response = ErrorResponse.class) }) @Permission(name = "View Users", permission = "/device-mgt/users/view") Response getRolesOfUser( - @ApiParam(name = "username", value = "Username of the user.", required = true) + @ApiParam( + name = "username", + value = "The username of the user.", + required = true, + defaultValue = "admin") @PathParam("username") String username, @ApiParam( name = "domain", - value = "Domain name of the user store.", + value = "The domain name of the user store.", required = false) @QueryParam("domain") String domain); @@ -305,14 +317,14 @@ public interface UserManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get user list", - notes = "If you wish to get the details of all the users registered with EMM, you can do so " + value = "Getting Details of Users", + notes = "You are able to manage users in WSO2 EMM by adding, updating and removing users. If you wish to get the list of users registered with WSO2 EMM, you can do so " + "using this REST API", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Successfully fetched the requested users.", + message = "OK. \n Successfully fetched the list of users registered with WSO2 EMM.", response = BasicUserInfoList.class, responseHeaders = { @ResponseHeader( @@ -324,42 +336,46 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported", response = ErrorResponse.class), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching the user list.", + message = "Internal Server Error. \n Server error occurred while fetching the list of WSO2 EMM users.", response = ErrorResponse.class) }) @Permission(name = "View Users", permission = "/device-mgt/users/view") Response getUsers( @ApiParam( name = "filter", - value = "Username of the user details to be fetched.", + value = "The username of the user.", required = false) @QueryParam("filter") String filter, @ApiParam( name = "If-Modified-Since", - value = "Timestamp of the last modified date", + value = "Checks if the requested variant was modified, since the specified date-time\n." + + "Provide the value in the Java Date Format: EEE, d MMM yyyy HH:mm:ss Z.\n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String timestamp, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many user details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @GET @@ -367,8 +383,8 @@ public interface UserManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get user count", - notes = "If you wish to get the user count registered with EMM, you can do so using this REST API", + value = "Getting the User Count", + notes = "Get the number of users in WSO2 EMM via this REST API.", tags = "User Management") @ApiResponses(value = { @ApiResponse( @@ -386,7 +402,7 @@ public interface UserManagementService { response = ErrorResponse.class), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching the user list.", + message = "Internal Server Error. \n Server error occurred while fetching the total number of users in WSO2 EMM.", response = ErrorResponse.class) }) @Permission(name = "View Users", permission = "/device-mgt/users/view") @@ -397,17 +413,16 @@ public interface UserManagementService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Search for a username.", - notes = "If you are unsure of the " - + "user name of a user and need to retrieve the details of a specific user, you can " + value = "Searching for a User Name", + notes = "If you are unsure of the user name of a user and need to retrieve the details of a specific user, you can " + "search for that user by giving a character or a few characters in the username. " - + "You will be given a list of users having the user name with the exact order of the " + + "You will be given a list of users having the user name in the exact order of the " + "characters you provided.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Successfully fetched the username list that matches the given filter.", + message = "OK. \n Successfully fetched the list of users that matched the given filter.", response = String.class, responseContainer = "List", responseHeaders = { @@ -420,43 +435,46 @@ public interface UserManagementService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported", response = ErrorResponse.class), @ApiResponse( code = 500, - message = "Internal Server Error. \n Server error occurred while fetching the username " + - "list that matches the given filter.", + message = "Internal Server Error. \n Server error occurred while fetching the list of users that matched the given filter.", response = ErrorResponse.class) }) @Permission(name = "View Users", permission = "/device-mgt/users/view") Response getUserNames( @ApiParam( name = "filter", - value = "Username/part of the user name to search.", + value = "Provide a character or a few character in the user name", required = true) @QueryParam("filter") String filter, @ApiParam( name = "If-Modified-Since", - value = "Timestamp of the last modified date", + value = "Checks if the requested variant was modified, since the specified date-time\n." + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n. " + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String timestamp, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many user details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); @PUT @@ -465,36 +483,37 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Changing the user password.", - notes = "A user is able to change the password to secure their EMM profile via this REST API.", + value = "Changing the User Password", + notes = "A user is able to change the password to secure their WSO2 EMM profile via this REST API.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Credentials of the user have been updated successfully"), + message = "OK. \n Successfully updated the user credentials."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format.", + message = "Unsupported media type. \n The format of the requested entity was not supported.", response = ErrorResponse.class), @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while updating credentials of the user.", + "Server error occurred while updating the user credentials.", response = ErrorResponse.class) }) @Permission(name = "Reset user password", permission = "/login") Response resetPassword( @ApiParam( name = "credentials", - value = "Credential.", + value = "The property to change the password.\n" + + "The password should be within 5 to 30 characters", required = true) OldPasswordResetWrapper credentials); @POST @@ -503,29 +522,30 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Send invitation mail.", - notes = "A user is able to send invitation mail via this REST API.", + value = "Sending Enrollment Invitations to Users", + notes = "Send the users a mail inviting them to download the EMM mobile application on their devices using the REST API given below.\n" + + "Before running the REST API command to send the enrollment invitations to users make sure to configure WSO2 EMM as explained in step 4, under the WSO2 EMM general server configurations documentation.", tags = "User Management") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Invitation mails have been sent."), + message = "OK. \n Successfully sent the invitation mail."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist.", + message = "Not Found. \n The specified resource does not exist.\n", response = ErrorResponse.class), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format.", + message = "Unsupported media type. \n The format of the requested entity was not supported.\n", response = ErrorResponse.class), @ApiResponse( code = 500, message = "Internal Server Error. \n " + - "Server error occurred while updating credentials of the user.", + "Server error occurred while updating the user credentials.", response = ErrorResponse.class) }) @Permission(name = "Manage Users", permission = "/device-mgt/users/manage") diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/DeviceManagementAdminService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/DeviceManagementAdminService.java index 1f4e0593755..47d138c534a 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/DeviceManagementAdminService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/DeviceManagementAdminService.java @@ -43,8 +43,8 @@ public interface DeviceManagementAdminService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get devices by name.", - notes = "Get devices by name of the device and tenant that they belong to.", + value = "Getting Details of a Device", + notes = "Get the details of a device by searching via the device name, device type and the tenant domain.", response = Device.class, responseContainer = "List", tags = "Device Management Administrative Service") @@ -62,20 +62,19 @@ public interface DeviceManagementAdminService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of " + - "the requested resource."), + message = "Not Modified. Empty body because the client already has the latest version of the requested resource.\n"), @ApiResponse( code = 401, - message = "Unauthorized.\n The requested resource access is unauthorized", + message = "Unauthorized.\n The unauthorized access to the requested resource.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found.\n No device found that matches the given name.", + message = "Not Found.\n The specified device does not exist", response = ErrorResponse.class), @ApiResponse( code = 406, @@ -89,37 +88,44 @@ public interface DeviceManagementAdminService { Response getDevicesByName( @ApiParam( name = "name", - value = "Name of the device.", + value = "The name of the device.If you are unsure of the name of the device, run the GET /devices API that is under Device Management.", required = true) @QueryParam("name") @Size(max = 45) String name, @ApiParam( name = "type", - value = "Type of the device.", - required = true) + value = "The type of the device, such as android, ios or windows.", + required = true, + allowableValues = "android, ios, windows") @QueryParam("type") @Size(min = 2, max = 45) String type, @ApiParam( name = "tenant-domain", - value = "Name of the tenant.", - required = true) + value = "The name of the tenant.\n" + + "The default tenant domain of WSO2 EMM is carbon.super", + required = true, + defaultValue = "carbon.super") @QueryParam("tenant-domain") String tenantDomain, @ApiParam( name = "If-Modified-Since", - value = "Validates if the requested variant has not been modified since the time specified", + value = "Checks if the requested variant was modified, since the specified date-time. \n" + + "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" + + "Example: Mon, 05 Jan 2014 15:10:00 +0200", required = false) @HeaderParam("If-Modified-Since") String ifModifiedSince, @ApiParam( name = "offset", - value = "Starting point within the complete list of items qualified.", - required = false) + value = "The starting pagination index for the complete list of qualified items.", + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", - value = "Maximum size of resource array to return.", - required = false) + value = "Provide how many activity details you require from the starting pagination index/offset.", + required = false, + defaultValue = "5") @QueryParam("limit") int limit); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java index 885005944a4..f5b17c14cbd 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java @@ -51,8 +51,9 @@ public interface GroupManagementAdminService { @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Get groups by the name.", - notes = "Get devices the name of device and tenant.", + value = "Grouping Devices", + notes = "Many devices can be registered with WSO2 IoTS. In order to manage them in an efficient manner, " + + "you can group devices and view the data gathered by the devices or share the groups with users so that they can monitor the devices in the respective group.", response = DeviceGroupWrapper.class, responseContainer = "List", tags = "Group Management Administrative Service") @@ -70,25 +71,24 @@ public interface GroupManagementAdminService { "Used by caches, or in conditional requests."), @ResponseHeader( name = "Last-Modified", - description = "Date and time the resource has been modified the last time.\n" + + description = "Date and time the resource was last modified.\n" + "Used by caches, or in conditional requests."), }), @ApiResponse( code = 304, - message = "Not Modified. \n Empty body because the client has already the latest version of the " + - "requested resource."), + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), @ApiResponse( code = 406, message = "Not Acceptable.\n The requested media type is not supported"), @ApiResponse( code = 500, - message = "Internal Server ErrorResponse. \n Server error occurred while fetching the group list.") + message = "Internal Server ErrorResponse. \n Server error occurred while fetching the list of device groups.") }) @Permission(name = "View All Groups", permission = "/permission/admin/device-mgt/user/groups/list") Response getGroupsOfUser( @ApiParam( name = "username", - value = "Username of the user.", + value = "The sername of the user.", required = true) @QueryParam("username") String username, @ApiParam( @@ -99,11 +99,13 @@ public interface GroupManagementAdminService { @ApiParam( name = "offset", value = "Starting point within the complete list of items qualified.", - required = false) + required = false, + defaultValue = "0") @QueryParam("offset") int offset, @ApiParam( name = "limit", value = "Maximum size of resource array to return.", - required = false) + required = false, + defaultValue = "5") @QueryParam("limit") int limit); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/UserManagementAdminService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/UserManagementAdminService.java index 026910d8e2e..039cfe8a776 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/UserManagementAdminService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/UserManagementAdminService.java @@ -46,23 +46,24 @@ public interface UserManagementAdminService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Change the user password.", - notes = "A user is able to change the password to secure their EMM profile via this REST API.", + value = "Changing the User Password.", + notes = "The EMM administrator is able to change the password of the users in " + + "the system and block them from logging into their EMM profile using this REST API.", tags = "User Management Administrative Service") @ApiResponses(value = { @ApiResponse( code = 200, - message = "OK. \n Credentials of the user have been updated successfully"), + message = "OK. \n Successfully updated the credentials of the user."), @ApiResponse( code = 400, message = "Bad Request. \n Invalid request or validation error.", response = ErrorResponse.class), @ApiResponse( code = 404, - message = "Not Found. \n Resource to be deleted does not exist."), + message = "Not Found. \n The resource to be deleted does not exist."), @ApiResponse( code = 415, - message = "Unsupported media type. \n The entity of the request was in a not supported format."), + message = "Unsupported media type. \n The format of the requested entity was not supported."), @ApiResponse( code = 500, message = "Internal Server Error. \n " + @@ -73,14 +74,15 @@ public interface UserManagementAdminService { Response resetUserPassword( @ApiParam( name = "username", - value = "Username of the user.", + value = "The username of the user." + + "INFO: Add a new user using the POST /users API that is under User Management.", required = true) @PathParam("username") @Size(max = 45) String username, @ApiParam( name = "domain", - value = "Domain name of the user store.", + value = "The domain name of the user store.", required = false) @QueryParam("domain") String domain, @ApiParam(