From 4623fa2269692bfedcfca308f7f4aca1e1cde8d1 Mon Sep 17 00:00:00 2001 From: inoshperera Date: Fri, 27 May 2016 11:55:58 +0530 Subject: [PATCH] swagger annotations added to APIs --- .../api/ActivityInfoProviderService.java | 25 +-- .../api/ConfigurationManagementService.java | 93 ++++++++++ .../service/api/DeviceManagementService.java | 57 ++++--- .../api/DeviceTypeManagementService.java | 97 ----------- .../api/NotificationManagementService.java | 98 +++++++---- .../service/api/PolicyManagementService.java | 126 +++++++++----- .../service/api/RoleManagementService.java | 161 ++++++++++++------ .../service/api/UserManagementService.java | 156 ++++++++++------- .../ApplicationManagementAdminService.java | 33 +++- .../admin/DeviceManagementAdminService.java | 33 +++- .../admin/GroupManagementAdminService.java | 28 ++- .../api/admin/UserManagementAdminService.java | 24 ++- ...mpl.java => ConfigurationServiceImpl.java} | 39 ++--- .../impl/PolicyManagementServiceImpl.java | 9 +- .../impl/RoleManagementServiceImpl.java | 17 ++ .../impl/UserManagementServiceImpl.java | 26 ++- .../DeviceManagementAdminServiceImpl.java | 6 +- .../src/main/webapp/WEB-INF/cxf-servlet.xml | 2 +- 18 files changed, 654 insertions(+), 376 deletions(-) create mode 100644 components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ConfigurationManagementService.java delete mode 100644 components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java rename components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/{DeviceTypeManagementServiceImpl.java => ConfigurationServiceImpl.java} (74%) 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 1844108c60f..895287c3826 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 @@ -18,10 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiParam; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.apimgt.annotations.api.Permission; import javax.ws.rs.*; @@ -31,7 +29,10 @@ import javax.ws.rs.core.Response; /** * Activity related REST-API implementation. */ +@API(name = "Activities", version = "1.0.0", context = "/devicemgt_admin/activities", tags = {"devicemgt_admin"}) @Path("/activities") +@Api(value = "ActivityInfo", description = "Activity related information manipulation. For example operation details " + + "and responses from devices.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface ActivityInfoProviderService { @@ -39,15 +40,19 @@ public interface ActivityInfoProviderService { @GET @Path("/{id}") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "POST", value = "Retrieving the operation details.", notes = "This will return the operation details including the responses from the devices.") - @ApiResponses(value = {@ApiResponse(code = 200, message = "Activity details provided successfully."), - @ApiResponse(code = 500, message = "Error occurred while fetching the activity for the supplied id.")}) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Activity details provided successfully."), + @ApiResponse(code = 500, message = "Error occurred while fetching the activity for the supplied id.") + }) @Permission(scope = "operation-view", permissions = {"/permission/admin/device-mgt/admin/devices/view"}) - Response getActivity(@ApiParam(name = "id", value = "Activity id of the operation/activity to be retrieved", - required = true) @PathParam("id") String id); + Response getActivity( + @ApiParam(name = "id", value = "Activity id of the operation/activity to be retrieved.", + required = true) + @PathParam("id") String id); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ConfigurationManagementService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ConfigurationManagementService.java new file mode 100644 index 00000000000..39c56c047ba --- /dev/null +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ConfigurationManagementService.java @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. + * + * WSO2 Inc. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * + */ +package org.wso2.carbon.device.mgt.jaxrs.service.api; + +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; +import org.wso2.carbon.apimgt.annotations.api.Permission; +import org.wso2.carbon.device.mgt.common.configuration.mgt.PlatformConfiguration; +import org.wso2.carbon.device.mgt.core.dto.DeviceType; + +import javax.ws.rs.*; +import javax.ws.rs.core.MediaType; +import javax.ws.rs.core.Response; + +/** + * General Tenant Configuration REST-API. + */ +@API(name = "Configuration", version = "1.0.0", context = "/devicemgt_admin/configuration", tags = {"devicemgt_admin"}) + +@Path("/configuration") +@Api(value = "Configuration", description = "General Tenant Configuration management capabilities are exposed " + + "through this API") +@Produces(MediaType.APPLICATION_JSON) +@Consumes(MediaType.APPLICATION_JSON) +public interface ConfigurationManagementService { + + @POST + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Configuring general platform settings", + notes = "Configure the general platform settings using this REST API.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Tenant configuration saved successfully"), + @ApiResponse(code = 500, message = "Error occurred while saving the tenant configuration") + }) + @Permission(scope = "configuration-modify", + permissions = {"/permission/admin/device-mgt/admin/platform-configs/modify"}) + Response saveConfiguration(@ApiParam(name = "configuration", value = "The required properties to " + + "update the platform configurations.", + required = true) PlatformConfiguration configuration); + + @GET + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Getting General Platform Configurations.", + notes = "Get the general platform level configuration details using this REST API.", + response = PlatformConfiguration.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Tenant configuration saved successfully."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the tenant configuration.") + }) + @Permission(scope = "configuration-view", + permissions = {"/permission/admin/device-mgt/admin/platform-configs/view"}) + Response getConfiguration(); + + @PUT + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "PUT", + value = "Updating General Platform Configurations.", + notes = "Update the notification frequency using this REST API.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Tenant configuration updated successfully."), + @ApiResponse(code = 500, message = "Error occurred while updating the tenant configuration.") + }) + @Permission(scope = "configuration-modify", + permissions = {"/permission/admin/device-mgt/admin/platform-configs/modify"}) + Response updateConfiguration(@ApiParam(name = "configuration", value = "The required properties to " + + "update the platform configurations.", + required = true) PlatformConfiguration configuration); + +} 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 8633279e65b..cb1e4e395c0 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 @@ -18,10 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiParam; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.apimgt.annotations.api.Permission; import org.wso2.carbon.device.mgt.common.DeviceIdentifier; import org.wso2.carbon.device.mgt.common.EnrolmentInfo; @@ -38,15 +36,18 @@ import java.util.Date; import java.util.List; /** - * Device related REST-API implementation. This can be used to manipulated device related details. + * Device related REST-API. This can be used to manipulated device related details. */ +@API(name = "Device", version = "1.0.0", context = "/devicemgt_admin/devices", tags = {"devicemgt_admin"}) @Path("/devices") +@Api(value = "Device", description = "Device related operations such as get all the available devices, etc.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Get the device list.", @@ -72,6 +73,7 @@ public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Get the device list corresponding to a device type.", @@ -117,6 +119,7 @@ public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Get the device list of a user.", @@ -141,6 +144,7 @@ public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Returns device list in a role.", @@ -165,6 +169,7 @@ public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Returns device list of an ownership scheme.", @@ -181,8 +186,7 @@ public interface DeviceManagementService { @Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"}) Response getDevicesByOwnership( @ApiParam(name = "ownership", value = "Ownership of the devices to be fetched registered under.", - required = true) - @QueryParam("ownership") EnrolmentInfo.OwnerShip ownership, + required = true) EnrolmentInfo.OwnerShip ownership, @ApiParam(name = "offset", value = "Starting pagination index.",required = true) @QueryParam("offset") int offset, @ApiParam(name = "limit", value = "How many device details are required from the starting pagination " + @@ -191,6 +195,7 @@ public interface DeviceManagementService { @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Returns device list", @@ -206,7 +211,7 @@ public interface DeviceManagementService { @Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"}) Response getDevicesByEnrollmentStatus( @ApiParam(name = "status", value = "Enrollment status of devices to be fetched.", required = true) - @QueryParam("status") EnrolmentInfo.Status status, + EnrolmentInfo.Status status, @ApiParam(name = "offset", value = "Starting pagination index.",required = true) @QueryParam("offset") int offset, @ApiParam(name = "limit", value = "How many device details are required from the starting pagination " + @@ -222,6 +227,7 @@ public interface DeviceManagementService { @GET @Path("/{type}/{id}/location") @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Get the device location of a given device and a device type.", @@ -238,14 +244,14 @@ public interface DeviceManagementService { Response getDeviceLocation( @ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true) @PathParam("type") String type, - @ApiParam(name = "type", value = "The device identifier of the device.", required = true) + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) @PathParam("id") String id); @GET @Path("/{type}/{id}/features") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + 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. " + @@ -256,13 +262,14 @@ public interface DeviceManagementService { @ApiResponses(value = { @ApiResponse(code = 200, message = "Successfully fetched the features.", response = org.wso2.carbon.device.mgt.common.Feature.class, responseContainer = "List"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the list of features.") }) + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of features.") + }) @Permission(scope = "device-search", permissions = {"/permission/admin/device-mgt/admin/devices/view", "/permission/admin/device-mgt/user/devices/view"}) Response getFeaturesOfDevice( @ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true) @PathParam("type") String type, - @ApiParam(name = "type", value = "The device identifier of the device.", required = true) + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) @PathParam("id") String id); @POST @@ -288,8 +295,8 @@ public interface DeviceManagementService { @GET @Path("/{type}/{id}/applications") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "GET", value = "Getting installed application details of a device.", responseContainer = "List", @@ -299,22 +306,24 @@ public interface DeviceManagementService { @ApiResponse(code = 200, message = "List of installed application details of a device.", response = Application.class, responseContainer = "List"), @ApiResponse(code = 404, message = "No installed applications found on the device searched."), - @ApiResponse(code = 500, message = "Error occurred while fetching the apps of the device.")}) + @ApiResponse(code = 500, message = "Error occurred while fetching the apps of the device.") + }) @Permission(scope = "operation-view", permissions = { "/permission/admin/device-mgt/admin/devices/view", - "/permission/admin/device-mgt/user/devices/view"}) + "/permission/admin/device-mgt/user/devices/view" + }) Response getInstalledApplications( @ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true) @PathParam("type") String type, - @ApiParam(name = "type", value = "The device identifier of the device.", required = true) + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) @PathParam("id") String id); @GET @Path("/{type}/{id}/operations") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + 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" + @@ -326,10 +335,12 @@ public interface DeviceManagementService { response = org.wso2.carbon.device.mgt.common.operation.mgt.Operation.class, responseContainer = "List"), @ApiResponse(code = 500, message = "Error occurred while fetching the operations for the " + - "device.")}) + "device.") + }) @Permission(scope = "operation-view", permissions = { "/permission/admin/device-mgt/admin/devices/view", - "/permission/admin/device-mgt/user/devices/view"}) + "/permission/admin/device-mgt/user/devices/view" + }) Response getDeviceOperations( @ApiParam(name = "offset", value = "Starting pagination index.",required = true) @QueryParam("offset") int offset, @@ -338,7 +349,7 @@ public interface DeviceManagementService { @QueryParam("limit") int limit, @ApiParam(name = "type", value = "The device type, such as ios, android or windows.", required = true) @PathParam("type") String type, - @ApiParam(name = "type", value = "The device identifier of the device.", required = true) + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) @PathParam("id") String id); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/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 deleted file mode 100644 index cf4ef4e08db..00000000000 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java +++ /dev/null @@ -1,97 +0,0 @@ -/* - * Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. - * - * WSO2 Inc. licenses this file to you under the Apache License, - * Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - * - */ -package org.wso2.carbon.device.mgt.jaxrs.service.api; - -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; -import org.wso2.carbon.apimgt.annotations.api.Permission; -import org.wso2.carbon.device.mgt.common.configuration.mgt.PlatformConfiguration; -import org.wso2.carbon.device.mgt.core.dto.DeviceType; - -import javax.ws.rs.*; -import javax.ws.rs.core.MediaType; -import javax.ws.rs.core.Response; - -@Path("/device-types") -@Produces(MediaType.APPLICATION_JSON) -@Consumes(MediaType.APPLICATION_JSON) -public interface DeviceTypeManagementService { - - @GET - @ApiOperation( - httpMethod = "GET", - value = "Getting Details of the Devices Supported via WSO2 EMM", - notes = "You are able to register Android, iOS and Windows devices with WSO2 EMM. This API will " - + "retrieve the device type details that can register with the EMM", - response = DeviceType.class, - responseContainer = "List") - @ApiResponses(value = { - @ApiResponse(code = 200, message = "List of devices based on the type"), - @ApiResponse(code = 500, message = "Error occurred while fetching the list of device types") }) - @Permission(scope = "device-list", permissions = {"/permission/admin/device-mgt/admin/devices/list"}) - Response getTypes(); - - @POST - @Path("/{type}/configuration") - @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - httpMethod = "POST", - value = "Configuring general platform settings", - notes = "Configure the general platform settings using this REST API") - @ApiResponses(value = { - @ApiResponse(code = 201, message = "Tenant configuration saved successfully"), - @ApiResponse(code = 500, message = "Error occurred while saving the tenant configuration") - }) - @Permission(scope = "configuration-modify", permissions = {"/permission/admin/device-mgt/admin/platform-configs/modify"}) - Response saveConfiguration(@PathParam("type") String type, PlatformConfiguration config); - - @GET - @Path("/{type}/configuration") - @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - httpMethod = "GET", - value = "Getting General Platform Configurations", - notes = "Get the general platform level configuration details using this REST API", - response = PlatformConfiguration.class) - @ApiResponses(value = { - @ApiResponse(code = 200, message = "OK"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the tenant configuration") - }) - @Permission(scope = "configuration-view", permissions = {"/permission/admin/device-mgt/admin/platform-configs/view"}) - Response getConfiguration(@PathParam("type") String type); - - @PUT - @Path("/{type}/configuration") - @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - httpMethod = "PUT", - value = "Updating General Platform Configurations", - notes = "Update the notification frequency using this REST API") - @ApiResponses(value = { - @ApiResponse(code = 201, message = "Tenant configuration updated successfully"), - @ApiResponse(code = 500, message = "Error occurred while updating the tenant configuration") - }) - @Permission(scope = "configuration-modify", permissions = {"/permission/admin/device-mgt/admin/platform-configs/modify"}) - Response updateConfiguration(@PathParam("type") String type, PlatformConfiguration config); - -} 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 bc1dcdf324d..f6824cce095 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 @@ -18,9 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.apimgt.annotations.api.Permission; import org.wso2.carbon.device.mgt.common.notification.mgt.Notification; @@ -28,6 +27,12 @@ import javax.ws.rs.*; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; +/** + * Notifications related REST-API. + */ +@API(name = "Device Notification", version = "1.0.0", context = "/devicemgt_admin/notifications", + tags = {"devicemgt_admin"}) +@Api(value = "DeviceNotification", description = "Device notification related operations can be found here.") @Path("/notifications") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @@ -35,75 +40,96 @@ public interface NotificationManagementService { @GET @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting all Device Notification Details", + value = "Getting all device notification details.", notes = "Get the details of all notifications that were pushed to the device in WSO2 EMM using " + "this REST API", response = Notification.class, responseContainer = "List") @ApiResponses(value = { - @ApiResponse(code = 200, message = "List of Notifications", response = Notification.class, - responseContainer = "List"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list") + @ApiResponse(code = 200, message = "Successfully fetched the list of notifications", + response = Notification.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No notification is available to be retrieved."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list.") }) @Permission(scope = "device-notification-view", permissions = { "/permission/admin/device-mgt/admin/notifications/view", - "/permission/admin/device-mgt/user/notifications/view"}) - Response getNotifications(@QueryParam("offset") int offset, @QueryParam("limit") int limit); + "/permission/admin/device-mgt/user/notifications/view" + }) + Response getNotifications( + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How notification device details are required from the starting " + + "pagination index.", required = true) + @QueryParam("limit") int limit); @GET @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting the Device Notifications Filtered by the Status", + value = "Getting the device notifications filtered by the status.", notes = "Get the details of all the unread notifications or the details of all the read " - + "notifications using this REST API", + + "notifications using this REST API.", response = Notification.class, responseContainer = "List") @ApiResponses(value = { - @ApiResponse(code = 200, message = "List of Notifications", response = Notification.class, - responseContainer = "List"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list") + @ApiResponse(code = 200, message = "Successfully fetched the list of notifications.", + response = Notification.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No notification, which carries the given status " + + "is available to be retrieved."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list.") }) @Permission(scope = "device-notification-view", permissions = { "/permission/admin/device-mgt/admin/notifications/view", - "/permission/admin/device-mgt/user/notifications/view"}) - Response getNotificationsByStatus(@QueryParam("status") Notification.Status status, - @QueryParam("offset") int offset, @QueryParam("limit") int limit); + "/permission/admin/device-mgt/user/notifications/view" + }) + Response getNotificationsByStatus( + @ApiParam(name = "status", value = "Status of the notification.",required = true) + Notification.Status status, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many notification details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @PUT @Path("/{id}/status") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Updating the Device Notification Status", - notes = "When a user has read the the device notification the device notification status must " - + "change from NEW to CHECKED. Update the device notification status using this REST API") + value = "Updating the device notification status", + notes = "When a user has read the the device notifications, the device notification status must " + + "change from NEW to CHECKED. Update the device notification status using this REST API.") @ApiResponses(value = { - @ApiResponse(code = 201, message = "Notification status updated successfully"), - @ApiResponse(code = 500, message = "Error occurred while updating notification status") + @ApiResponse(code = 201, message = "Notification status updated successfully."), + @ApiResponse(code = 500, message = "Error occurred while updating notification status.") }) @Permission(scope = "device-notification-modify", permissions = {"/permission/admin/device-mgt/admin/notifications/modify"}) - Response updateNotificationStatus(@PathParam("id") int id, Notification.Status status); + Response updateNotificationStatus( + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) + @PathParam("id") int id, + @ApiParam(name = "status", value = "Status of the notification.",required = true) + Notification.Status status); @POST @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Sending a Device Notification", - notes = "Notify users on device operation failures and other information using this REST API") + value = "Sending a device notification.", + notes = "Notify users on device operation failures and other information using this REST API.") @ApiResponses(value = { - @ApiResponse(code = 201, message = "NNotification has added successfully"), - @ApiResponse(code = 500, message = "Error occurred while updating notification status") + @ApiResponse(code = 201, message = "Notification has added successfully."), + @ApiResponse(code = 500, message = "Error occurred while updating notification status.") }) @Permission(scope = "device-notification-modify", permissions = {"/permission/admin/device-mgt/admin/notifications/modify"}) - Response addNotification(Notification notification); + Response addNotification(@ApiParam(name = "notification", value = "Notification details to be added.",required = + true) Notification notification); } 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 e5ef3071e2a..82f43a69e15 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 @@ -19,6 +19,7 @@ package org.wso2.carbon.device.mgt.jaxrs.service.api; import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; import org.wso2.carbon.apimgt.annotations.api.Permission; @@ -29,6 +30,10 @@ import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import java.util.List; +/** + * Policy related REST-API. This can be used to manipulated policies and associate them with devices, users, roles, + * groups. + */ @Path("/policies") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @@ -39,44 +44,59 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Adding a Policy.", - notes = "Add a policy using this REST API command. When adding a policy you will have the option of " + - "saving the policy or saving and publishing the policy. Using the REST API command given below " + - "you are able to save a created Policy and this policy will be in the inactive state") - @ApiResponses(value = {@ApiResponse(code = 201, message = "Created the policy."), - @ApiResponse(code = 500, message = "Policy Management related error occurred when " + - "adding the policy")}) + value = "Adding a policy.", + notes = "Add a policy using this REST API command. Using the REST API command given below " + + "you are able to save a created Policy and this policy will be in the inactive state.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Created the policy."), + @ApiResponse(code = 401, message = "Current user is not authorized to add policies."), + @ApiResponse(code = 500, message = "Policy Management related error occurred when adding the policy.")}) @Permission(scope = "policy-modify", permissions = {"/permission/admin/device-mgt/admin/policies/add"}) - Response addPolicy(PolicyWrapper policy); + Response addPolicy(@ApiParam(name = "policy", value = "Policy details related to the operation.", + required = true) PolicyWrapper policy); @GET @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Details of Policies.", + value = "Getting details of policies.", responseContainer = "List", - notes = "Retrieve the details of all the policies that you have created in WSO2 EMM.", + notes = "Retrieve the details of all the policies that you have created in EMM.", response = org.wso2.carbon.policy.mgt.common.Policy.class) - @ApiResponses(value = {@ApiResponse(code = 200, message = "Fetched all policies.", + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Fetched all policies.", response = org.wso2.carbon.policy.mgt.common.Policy.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No policies found."), @ApiResponse(code = 500, message = "Policy Management related error occurred when " + - "fetching the policies.")}) + "fetching the policies.") + }) @Permission(scope = "policy-view", permissions = {"/permission/admin/device-mgt/admin/policies/list"}) - Response getPolicies(@QueryParam("offset") int offset, @QueryParam("limit") int limit); + Response getPolicies( + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many policy details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @GET @Path("/{id}") @ApiOperation( produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Details of a Policy.", - notes = "Retrieve the details of a selected policy in WSO2 EMM.", + value = "Getting details of a policy.", + notes = "Retrieve the details of a given policy in EMM.", response = org.wso2.carbon.policy.mgt.common.Policy.class) - @ApiResponses(value = {@ApiResponse(code = 200, message = "Fetched policy details."), - @ApiResponse(code = 500, message = "Policy Management related error occurred when " + - "fetching the policies.")}) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Fetched policy details.", + response = org.wso2.carbon.policy.mgt.common.Policy.class), + @ApiResponse(code = 404, message = "Policy not found."), + @ApiResponse(code = 500, message = "Policy management related error occurred when " + + "fetching the policy.") + }) @Permission(scope = "policy-view", permissions = {"/permission/admin/device-mgt/admin/policies/list"}) - Response getPolicy(@PathParam("id") int id); + Response getPolicy( + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) + @PathParam("id") int id); @PUT @Path("/{id}") @@ -84,27 +104,35 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Updating a Policy.", + value = "Updating a policy.", notes = "If you wish to make changes to an existing policy, you can do so by updating the policy using " + - "this API") - @ApiResponses(value = {@ApiResponse(code = 201, message = "Policy has been updated successfully."), - @ApiResponse(code = 500, message = "Policy Management related exception in policy " + - "update")}) + "this API.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Policy has been updated successfully."), + @ApiResponse(code = 500, message = "Policy management related exception in policy update.") + }) @Permission(scope = "policy-modify", permissions = {"/permission/admin/device-mgt/admin/policies/update"}) - Response updatePolicy(@PathParam("id") int id, PolicyWrapper policyWrapper); + Response updatePolicy( + @ApiParam(name = "id", value = "The device identifier of the device.", required = true) + @PathParam("id") int id, + @ApiParam(name = "policy", value = "Policy details related to the operation.", + required = true) PolicyWrapper policy); @POST @ApiOperation( consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Removing Multiple Policies.", + value = "Removing multiple policies.", notes = "In situations where you need to delete more than one policy you can do so using this API.") - @ApiResponses(value = {@ApiResponse(code = 200, message = "Policies have been successfully deleted."), - @ApiResponse(code = 400, message = "Policy does not exist."), - @ApiResponse(code = 500, message = "Error in deleting policies.")}) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Policies have been successfully deleted."), + @ApiResponse(code = 404, message = "Policy does not exist."), + @ApiResponse(code = 500, message = "Error in deleting policies.") + }) @Permission(scope = "policy-modify", permissions = {"/permission/admin/device-mgt/admin/policies/remove"}) - Response removePolicies(List policyIds); + Response removePolicies(@ApiParam(name = "policyIds", value = "Policy ID list to be deleted.", + required = true) List policyIds); @POST @Path("/activate-policy") @@ -112,15 +140,19 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Activating Policies.", + value = "Activating policies.", notes = "Using the REST API command you are able to publish a policy in order to bring a policy that is " + "in the inactive state to the active state.") - @ApiResponses(value = {@ApiResponse(code = 200, message = "Policies have been successfully activated."), - @ApiResponse(code = 500, message = "Error in activating policies.")}) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Policies have been successfully activated."), + @ApiResponse(code = 500, message = "Error in activating policies.") + }) @Permission(scope = "policy-modify", permissions = { "/permission/admin/device-mgt/admin/policies/update", "/permission/admin/device-mgt/admin/policies/add"}) - Response activatePolicies(List policyIds); + Response activatePolicies( + @ApiParam(name = "policyIds", value = "Policy ID list to be activated.", + required = true) List policyIds); @POST @Path("/deactivate-policy") @@ -128,15 +160,19 @@ public interface PolicyManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Deactivating Policies.", + value = "Deactivating policies.", notes = "Using the REST API command you are able to unpublish a policy in order to bring a policy that " + "is in the active state to the inactive state.") - @ApiResponses(value = {@ApiResponse(code = 200, message = "Policies have been successfully deactivated."), - @ApiResponse(code = 500, message = "Error in deactivating policies.")}) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Policies have been successfully deactivated."), + @ApiResponse(code = 500, message = "Error in deactivating policies.") + }) @Permission(scope = "policy-modify", permissions = { "/permission/admin/device-mgt/admin/policies/update", "/permission/admin/device-mgt/admin/policies/add"}) - Response deactivatePolicies(List policyIds); + Response deactivatePolicies( + @ApiParam(name = "policyIds", value = "Policy ID list to be deactivated.", + required = true) List policyIds); @GET @ApiOperation( @@ -147,9 +183,15 @@ public interface PolicyManagementService { "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.", response = org.wso2.carbon.policy.mgt.common.Policy.class) - @ApiResponses(value = {@ApiResponse(code = 200, message = "Fetched current policy."), - @ApiResponse(code = 500, message = "Error occurred while getting the current policy.")}) - Response getEffectivePolicyOfDevice(@QueryParam("device-type") String type, - @QueryParam("device-id") String deviceId); + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Fetched current policy."), + @ApiResponse(code = 404, message = "No policy found."), + @ApiResponse(code = 500, message = "Error occurred while getting the current policy.") + }) + Response getEffectivePolicyOfDevice( + @ApiParam(name = "device-type", value = "The device type, such as ios, android or windows.", required = true) + @QueryParam("device-type") String type, + @ApiParam(name = "device-id", value = "The device identifier of the device.", required = true) + @QueryParam("device-id") String deviceId); } 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 13adac844ee..f9c706da966 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 @@ -18,9 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.apimgt.annotations.api.Permission; import org.wso2.carbon.device.mgt.jaxrs.beans.RoleWrapper; import org.wso2.carbon.user.mgt.common.UIPermissionNode; @@ -30,7 +29,9 @@ import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import java.util.List; +@API(name = "Role", version = "1.0.0", context = "/devicemgt_admin/roles", tags = {"devicemgt_admin"}) @Path("/roles") +@Api(value = "Role", description = "Role management related operations can be found here.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface RoleManagementService { @@ -40,56 +41,85 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting the List of Roles.", + value = "Getting the list of roles.", responseContainer = "List", - notes = "If you wish to get the details of all the roles in WSO2 EMM, you can do so using this REST API.", + notes = "If you wish to get the details of all the roles in EMM, you can do so using this REST API. All " + + "internal roles, roles created for Service-providers and application related roles are omitted.", response = String.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "List of available roles"), - @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched the list of available roles", + response = String.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No roles found."), + @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") + }) @Permission(scope = "roles-view", permissions = { "/permission/admin/device-mgt/admin/roles/list", "/permission/admin/device-mgt/admin/users/view", "/permission/admin/device-mgt/admin/policies/add", "/permission/admin/device-mgt/admin/policies/update"}) - Response getRoles(@QueryParam("offset") int offset, @QueryParam("limit") int limit); + Response getRoles( + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many role details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @GET @ApiOperation( consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting the List of Roles in a User Store.", + value = "Getting the list of roles in a user store.", responseContainer = "List", - notes = "If you wish to get the details of all the roles in WSO2 EMM, you can do so using this REST API.", + notes = "If you wish to get the details of all the roles in EMM, you can do so using this REST API.", response = String.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "List of available roles"), - @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched the list of available roles", + response = String.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No roles found."), + @ApiResponse(code = 500, message = "Error occurred while fetching the role list.") + }) @Permission(scope = "roles-view", permissions = { "/permission/admin/device-mgt/admin/users/add", "/permission/admin/device-mgt/admin/roles/list"}) - Response getRoles(@QueryParam("user-store") String userStoreName, @QueryParam("offset") int offset, - @QueryParam("limit") int limit); + Response getRoles( + @ApiParam(name = "user-store", value = "From which user store the roles must be fetched.",required = true) + @QueryParam("user-store") String userStoreName, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many role details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @GET @ApiOperation( consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Searching for Roles via the Role Name.", + value = "Searching for roles via the role name.", responseContainer = "List", - notes = "You will have many roles created within WSO2 EMM. As the admin you will need to confirm if a " + + notes = "You will have many roles created within EMM. As the admin you will need to confirm if a " + "given role exists in the EMM. In such situation you can search for the role by giving a " + "character or a few characters of the role name. The search will give you a list of roles that" + " have the name in the exact order of the characters you provided.", response = String.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "List of matching roles"), - @ApiResponse(code = 500, message = "Error occurred while fetching the matching role list" + - ".") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched the list of matching roles.", + response = String.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No roles found."), + @ApiResponse(code = 500, message = "Error occurred while fetching the matching role list.") + }) @Permission(scope = "roles-view", permissions = { "/permission/admin/device-mgt/admin/users/add", "/permission/admin/device-mgt/admin/roles/list"}) - Response searchRoles(@QueryParam("filter") String filter, @QueryParam("offset") int offset, - @QueryParam("limit") int limit); + Response searchRoles( + @ApiParam(name = "filter", value = "Role name or a part of it to search.",required = true) + @QueryParam("filter") String filter, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many role details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @GET @Path("/{roleName}/permissions") @@ -97,17 +127,21 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Permission Details of a Role.", + value = "Getting permission details of a role.", notes = "In an organization an individual is associated a with set of responsibilities based on their " + - "role. In WSO2 EMM you are able to configure permissions based on the responsibilities carried " + + "role. In EMM you are able to configure permissions based on the responsibilities carried " + "out by a role. Therefore if you wish to retrieve the permission details of a role, you can do " + "so using this REST API.", response = UIPermissionNode.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "Permission details of a role"), - @ApiResponse(code = 500, message = "Error occurred while fetching the permission " + - "details of a role.") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Permission details of a role", response = UIPermissionNode.class), + @ApiResponse(code = 404, message = "No permissions found for the role."), + @ApiResponse(code = 500, message = "Error occurred while fetching the permission details of a role.") + }) @Permission(scope = "roles-view", permissions = {"/permission/admin/device-mgt/admin/roles/list"}) - Response getPermissionsOfRole(@PathParam("roleName") String roleName); + Response getPermissionsOfRole( + @ApiParam(name = "roleName", value = "Name of the role.",required = true) + @PathParam("roleName") String roleName); @GET @Path("/{roleName}") @@ -115,25 +149,34 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Details of a Role.", - notes = "If you wish to get the details of a role in WSO2 EMM, you can do so using this REST API.", + value = "Getting details of a role.", + notes = "If you wish to get the details of a role in EMM, you can do so using this REST API.", response = RoleWrapper.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "Details of a role."), - @ApiResponse(code = 500, message = "Error occurred while retrieving the user role.") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched the role details.", response = RoleWrapper.class), + @ApiResponse(code = 404, message = "No role details found for the provided role name."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the role details.") + }) @Permission(scope = "roles-view", permissions = {"/permission/admin/device-mgt/admin/roles/list"}) - Response getRole(@PathParam("roleName") String roleName); + Response getRole( + @ApiParam(name = "roleName", value = "Name of the role.",required = true) + @PathParam("roleName") String roleName); @POST @ApiOperation( consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Adding a Role.", - notes = "You are able to add a new role to WSO2 EMM using the REST API.") - @ApiResponses(value = { @ApiResponse(code = 200, message = "Added the role."), - @ApiResponse(code = 500, message = "Error occurred while adding the user role.") }) + value = "Adding a role.", + notes = "You are able to add a new role to EMM using the REST API.") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Added the role."), + @ApiResponse(code = 500, message = "Error occurred while adding the user role.") + }) @Permission(scope = "roles-modify", permissions = {"/permission/admin/device-mgt/admin/roles/add"}) - Response addRole(RoleWrapper role); + Response addRole( + @ApiParam(name = "role", value = "Details about the role to be added.",required = true) + RoleWrapper role); @PUT @Path("/{roleName}") @@ -141,14 +184,19 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Updating a Role.", + value = "Updating a role.", notes = "There will be situations where you will need to update the role details, such as the permissions" + " or the role name. In such situation you can update the role details.") - @ApiResponses(value = { @ApiResponse(code = 200, message = "Updated the role."), - @ApiResponse(code = 500, message = "Error occurred while updating the user role details" + - ".") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Updated the role."), + @ApiResponse(code = 500, message = "Error occurred while updating the user role details.") + }) @Permission(scope = "roles-modify", permissions = {"/permission/admin/device-mgt/admin/roles/update"}) - Response updateRole(@PathParam("roleName") String roleName, RoleWrapper role); + Response updateRole( + @ApiParam(name = "roleName", value = "Name of the role.",required = true) + @PathParam("roleName") String roleName, + @ApiParam(name = "role", value = "Details about the role to be added.",required = true) + RoleWrapper role); @DELETE @Path("/{roleName}") @@ -156,14 +204,17 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "DELETE", - value = "Deleting a Role.", + value = "Deleting a role.", notes = "In a situation when your Organization identifies that a specific role is no longer required you " + - "will need to remove the role details from WSO2 EMM.") - @ApiResponses(value = { @ApiResponse(code = 200, message = "Deleted the role."), - @ApiResponse(code = 500, message = "Error occurred while deleting the user role details" + - ".") }) + "will need to remove the role details from EMM.") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Deleted the role."), + @ApiResponse(code = 500, message = "Error occurred while deleting the user role details.") + }) @Permission(scope = "roles-modify", permissions = {"/permission/admin/device-mgt/admin/roles/remove"}) - Response deleteRole(@PathParam("roleName") String roleName); + Response deleteRole( + @ApiParam(name = "roleName", value = "Name of the role to de deleted.",required = true) + @PathParam("roleName") String roleName); @POST @Path("/{roleName}/users") @@ -171,16 +222,22 @@ public interface RoleManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Adding Users to a Role.", + value = "Adding users to a role.", notes = "Defining the users to a role at the point of creating a new role is optional, " + "therefore you are able to update the users that belong to a given role after you have created " + "a role using this REST API." + "Example: Your Organization hires 30 new engineers. Updating the role details for each user can " + "be cumbersome, therefore you can define all the new employees that belong to the engineering " + "role using this API.") - @ApiResponses(value = { @ApiResponse(code = 200, message = "Added Users to a Role."), - @ApiResponse(code = 500, message = "Error occurred while saving the users of the role.") }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Added Users to a Role."), + @ApiResponse(code = 500, message = "Error occurred while saving the users of the role.") + }) @Permission(scope = "roles-modify", permissions = {"/permission/admin/device-mgt/admin/roles/update"}) - Response updateUsersOfRole(@PathParam("roleName") String roleName, List users); + Response updateUsersOfRole( + @ApiParam(name = "roleName", value = "Name of the role.",required = true) + @PathParam("roleName") String roleName, + @ApiParam(name = "users", value = "List of usernames to be added.",required = true) + 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 8b2da1a3391..a825051400f 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 @@ -18,9 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api; -import io.swagger.annotations.ApiOperation; -import io.swagger.annotations.ApiResponse; -import io.swagger.annotations.ApiResponses; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.apimgt.annotations.api.Permission; import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.UserWrapper; @@ -29,7 +28,10 @@ import javax.ws.rs.*; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; + +@API(name = "UserManagement", version = "1.0.0", context = "/devicemgt_admin/users", tags = {"devicemgt_admin"}) @Path("/users") +@Api(value = "UserManagement", description = "User management related operations can be found here.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface UserManagementService { @@ -39,122 +41,154 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Adding a User via the REST API", - notes = "Adds a new user to WSO2 EMM using this REST API") + value = "Adding a user.", + notes = "Adds a new user to EMM using this REST API.") @ApiResponses(value = { - @ApiResponse(code = 201, message = "Created"), - @ApiResponse(code = 500, message = "Exception in trying to add user by username: 'username'") + @ApiResponse(code = 201, message = "Added the user successfully."), + @ApiResponse(code = 500, message = "Exception in trying to add the user.") }) @Permission(scope = "user-modify", permissions = {"/permission/admin/device-mgt/admin/user/add"}) - Response addUser(UserWrapper user); + Response addUser( + @ApiParam(name = "user", value = "User related details.",required = true) UserWrapper user); @GET @Path("/{username}") @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Details of a User", - notes = "If you wish to get the details of a specific user that is registered with WSO2 EMM," - + " you can do so using the REST API", + 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.", response = UserWrapper.class) @ApiResponses(value = { - @ApiResponse(code = 201, message = "User information was retrieved successfully"), - @ApiResponse(code = 400, message = "User by username: 'username' does not exist"), - @ApiResponse(code = 500, message = "Exception in trying to retrieve user by username: 'username'") + @ApiResponse(code = 201, message = "User information was retrieved successfully.", + response = UserWrapper.class), + @ApiResponse(code = 404, message = "User by the provided username does not exist."), + @ApiResponse(code = 500, message = "Exception in trying to retrieve user by username.") }) @Permission(scope = "user-view", permissions = {"/permission/admin/device-mgt/admin/user/view"}) - Response getUser(@PathParam("username") String username); + Response getUser( + @ApiParam(name = "username", value = "Username of the user to be fetched.",required = true) + @PathParam("username") String username); @PUT @Path("/{username}") @ApiOperation( - consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, - produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, httpMethod = "PUT", - value = "Updating 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") + + "situation you can update the user details using this REST API.") @ApiResponses(value = { - @ApiResponse(code = 200, message = "User by username: 'username' was successfully updated"), - @ApiResponse(code = 409, message = "User by username: 'username' doesn't exists. Therefore, " - + "request made to update user was refused"), + @ApiResponse(code = 200, message = "User was successfully updated"), + @ApiResponse(code = 409, message = "User by the provided username doesn't exists. Therefore, " + + "request made to update user was refused."), @ApiResponse(code = 500, message = "Exception in trying to update user by username: 'username'") }) @Permission(scope = "user-modify", permissions = {"/permission/admin/device-mgt/admin/user/update"}) - Response updateUser(@PathParam("username") String username, UserWrapper user); + Response updateUser( + @ApiParam(name = "username", value = "Username of the user to be updated.",required = true) + @PathParam("username") String username, + @ApiParam(name = "user", value = "User related details.",required = true) + UserWrapper user); @DELETE @Path("/{username}") @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "DELETE", - value = "Deleting a User", + value = "Deleting a user.", notes = "In a situation where an employee leaves the organization you will need to remove the" - + " user details from WSO2 EMM. In such situations you can use this REST API " - + "to remove a user") + + " user details from EMM. In such situations you can use this REST API to remove a user.") @ApiResponses(value = { - @ApiResponse(code = 200, message = "User by username: 'username' was successfully removed"), - @ApiResponse(code = 400, message = "User by username: 'username' does not exist for removal"), - @ApiResponse(code = 500, message = "Exception in trying to remove user by username: 'username'") + @ApiResponse(code = 200, message = "User was successfully removed."), + @ApiResponse(code = 404, message = "User does not exist for removal."), + @ApiResponse(code = 500, message = "Exception in trying to remove user.") }) @Permission(scope = "user-modify", permissions = {"/permission/admin/device-mgt/admin/user/remove"}) - Response removeUser(@PathParam("username") String username); + Response removeUser( + @ApiParam(name = "username", value = "Username of the user to be deleted.",required = true) + @PathParam("username") String username); @POST @Path("/{username}/roles") @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting the Role Details of a User", - notes = "A user can be assigned to one or more role in WSO2 EMM. Using this REST API you are " - + "able to get the role/roles a user is assigned to", + 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 are " + + "able to get the role/roles a user is assigned to.", response = String.class, responseContainer = "List") @ApiResponses(value = { - @ApiResponse(code = 200, message = "User roles obtained for user : 'username'"), - @ApiResponse(code = 400, message = "User by username: 'username' does not exist for role retrieval"), - @ApiResponse(code = 500, message = "Exception in trying to retrieve roles for user by username: 'username'") + @ApiResponse(code = 200, message = "User roles obtained for the provided user.", response = String.class, + responseContainer = "List"), + @ApiResponse(code = 404, message = "User does not exist for role retrieval."), + @ApiResponse(code = 500, message = "Exception in trying to retrieve roles for the provided user.") }) @Permission(scope = "user-view", permissions = {"/permission/admin/device-mgt/admin/user/view"}) - Response getRolesOfUser(@PathParam("username") String username); + Response getRolesOfUser( + @ApiParam(name = "username", value = "Username of the user.",required = true) + @PathParam("username") String username); @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Getting Details of Users", - notes = "If you wish to get the details of all the user registered with WSO2 EMM, you can do so " + value = "Getting details of users", + notes = "If you wish to get the details of all the user registered with EMM, you can do so " + "using the REST API", response = UserWrapper.class, responseContainer = "List") @ApiResponses(value = { - @ApiResponse(code = 200, message = "All users were successfully retrieved"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users") + @ApiResponse(code = 200, message = "All users were successfully retrieved.", response = UserWrapper.class, + responseContainer = "List"), + @ApiResponse(code = 404, message = "No users found."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users.") }) @Permission(scope = "user-view", permissions = {"/permission/admin/device-mgt/admin/user/list"}) - Response getUsers(@QueryParam("filter") String filter, @QueryParam("offset") int offset, - @QueryParam("limit") int limit); + Response getUsers( + @ApiParam(name = "filter", value = "Username of the user details to be fetched.",required = true) + @QueryParam("filter") String filter, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many user details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @GET @ApiOperation( + consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Searching for a User Name", - notes = "You will have 100+ users registered with WSO2 EMM. Therefore if you are unsure of the " + value = "Searching 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 " + "search for that user by giving a character or a few characters in the username. " + "You will be given a list of users having the user name with the exact order of the " - + "characters you provided", + + "characters you provided.", response = String.class, responseContainer = "List") @ApiResponses(value = { - @ApiResponse(code = 200, message = "All users by username were successfully retrieved. Obtained" - + " user count: 'count'"), - @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users") + @ApiResponse(code = 200, message = "All users by username were successfully retrieved.", + response = String.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No users found."), + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users.") }) @Permission(scope = "user-view", permissions = {"/permission/admin/device-mgt/admin/user/list"}) - Response getUserNames(@QueryParam("filter") String filter, @QueryParam("offset") int offset, - @QueryParam("limit") int limit); + Response getUserNames( + @ApiParam(name = "filter", value = "Username/part of the user name to search.",required = true) + @QueryParam("filter") String filter, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many user details are required from the starting pagination " + + "index.", required = true) + @QueryParam("limit") int limit); @PUT @Path("/{username}/credentials") @@ -162,17 +196,19 @@ public interface UserManagementService { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "POST", - value = "Changing the User Password", - notes = "A user is able to change the password to secure their EMM profile via this REST API") + value = "Changing the user password.", + notes = "A user is able to change the password to secure their EMM profile via this REST API.") @ApiResponses(value = { - @ApiResponse(code = 201, message = "UserImpl password by username: 'Username' was " - + "successfully changed"), - @ApiResponse(code = 400, message = "Old password does not match"), - @ApiResponse(code = 400, message = "Could not change the password of the user: 'Username'. The" - + " Character Encoding is not supported"), - @ApiResponse(code = 500, message = "Internal Server Error") + @ApiResponse(code = 201, message = "User password was successfully changed."), + @ApiResponse(code = 400, message = "Old password does not match."), + @ApiResponse(code = 500, message = "Could not change the password of the user. The Character encoding is" + + " not supported.") }) @Permission(scope = "user-modify", permissions = {"/permission/admin/login"}) - Response resetPassword(@PathParam("username") String username, UserCredentialWrapper credentials); + Response resetPassword( + @ApiParam(name = "username", value = "Username of the user.",required = true) + @PathParam("username") String username, + @ApiParam(name = "credentials", value = "Credential.",required = true) + UserCredentialWrapper credentials); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/ApplicationManagementAdminService.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/ApplicationManagementAdminService.java index 2d4e4cc781a..b5745612ff4 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/ApplicationManagementAdminService.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/ApplicationManagementAdminService.java @@ -18,6 +18,8 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api.admin; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; import org.wso2.carbon.device.mgt.jaxrs.beans.ApplicationWrapper; import javax.ws.rs.Consumes; @@ -27,17 +29,44 @@ import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; +@API(name = "Application", version = "1.0.0", context = "/devicemgt_admin/applications", tags = {"devicemgt_admin"}) + @Path("/applications") +@Api(value = "Application", description = "Application related operations are exposed through this API.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface ApplicationManagementAdminService { @POST @Path("/install-application") - Response installApplication(ApplicationWrapper applicationWrapper); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Application installation API.(Internal API)", + notes = "This is an internal API used for application installation on a device.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Application wil be installed on the device."), + @ApiResponse(code = 500, message = "Error while adding the application install operation.") + }) + Response installApplication( + @ApiParam(name = "applicationWrapper", value = "Application details of the application to be installed.", + required = true) ApplicationWrapper applicationWrapper); @POST @Path("/uninstall-application") - Response uninstallApplication(ApplicationWrapper applicationWrapper); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Application uninstallation API.(Internal API)", + notes = "This is an internal API used for application uninstallation on a device.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Application wil be uninstalled on the device."), + @ApiResponse(code = 500, message = "Error while adding the application uninstall operation.") + }) + Response uninstallApplication( + @ApiParam(name = "applicationWrapper", value = "Application details of the application to be uninstalled.", + required = true) ApplicationWrapper applicationWrapper); } 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 8bba985eec3..d8018e778b0 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 @@ -18,18 +18,41 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api.admin; -import javax.ws.rs.Consumes; -import javax.ws.rs.Path; -import javax.ws.rs.Produces; -import javax.ws.rs.QueryParam; +import io.swagger.annotations.*; +import org.wso2.carbon.apimgt.annotations.api.API; + +import javax.ws.rs.*; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; +@API(name = "DeviceManagementAdmin", version = "1.0.0", context = "/devicemgt_admin/applications", + tags = {"devicemgt_admin"}) @Path("/devices") +@Api(value = "DeviceManagementAdmin", description = "Device management admin related operations are exposed through " + + "this API.") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public interface DeviceManagementAdminService { - Response getDevicesByName(@QueryParam("name") String name, @QueryParam("tenant-domain") String tenantDomain); + @GET + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Get devices by the name.", + notes = "Get devices the name of device and tenant.", + response = org.wso2.carbon.device.mgt.common.Device.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched device details.", + response = org.wso2.carbon.device.mgt.common.Device.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "No matching device found in the provided tenant."), + @ApiResponse(code = 500, message = "Error while fetching device information.") + }) + Response getDevicesByName( + @ApiParam(name = "name", value = "Name of the device.",required = true) + @QueryParam("name") String name, + @ApiParam(name = "tenant-domain", value = "Name of the tenant.",required = true) + @QueryParam("tenant-domain") String tenantDomain); } 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 7d8d9846f8f..3dc09eefcb4 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 @@ -18,6 +18,10 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api.admin; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.wso2.carbon.apimgt.annotations.api.Permission; import javax.ws.rs.*; @@ -30,9 +34,29 @@ import javax.ws.rs.core.Response; public interface GroupManagementAdminService { @GET + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Get groups by the name.", + notes = "Get devices the name of device and tenant.", + response = org.wso2.carbon.device.mgt.common.Device.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Successfully fetched group details.", + response = org.wso2.carbon.device.mgt.common.Device.class, responseContainer = "List"), + @ApiResponse(code = 404, message = "Device not found."), + @ApiResponse(code = 500, message = "Error while fetching group information.") + }) @Permission(scope = "group-view", permissions = {"/permission/admin/device-mgt/user/groups/list"}) - Response getGroupsOfUser(@QueryParam("username") String username, @QueryParam("offset") int offset, - @QueryParam("limit") int limit); + Response getGroupsOfUser( + @ApiParam(name = "username", value = "Username of the user.",required = true) + @QueryParam("username") String username, + @ApiParam(name = "offset", value = "Starting pagination index.",required = true) + @QueryParam("offset") int offset, + @ApiParam(name = "limit", value = "How many policy details are required from the starting pagination " + + "index.", required = true) + @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 fd7b8f85345..08e53cf0eaa 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 @@ -18,6 +18,11 @@ */ package org.wso2.carbon.device.mgt.jaxrs.service.api.admin; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; +import org.wso2.carbon.apimgt.annotations.api.Permission; import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper; import javax.ws.rs.*; @@ -31,6 +36,23 @@ public interface UserManagementAdminService { @POST @Path("/{username}/credentials") - Response resetPassword(@PathParam("username") String user, UserCredentialWrapper credentials); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Changing the user password.", + notes = "A user is able to change the password to secure their EMM profile via this REST API.") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "User password was successfully changed."), + @ApiResponse(code = 400, message = "Old password does not match."), + @ApiResponse(code = 500, message = "Could not change the password of the user. The Character encoding is" + + " not supported.") + }) + @Permission(scope = "user-modify", permissions = {"/permission/admin/login"}) + Response resetPassword( + @ApiParam(name = "username", value = "Username of the user.",required = true) + @PathParam("username") String username, + @ApiParam(name = "credentials", value = "Credential.",required = true) + UserCredentialWrapper credentials); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceTypeManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/ConfigurationServiceImpl.java similarity index 74% rename from components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceTypeManagementServiceImpl.java rename to components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/ConfigurationServiceImpl.java index eb908c70ee0..c1ce58ae8b9 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/DeviceTypeManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/ConfigurationServiceImpl.java @@ -23,10 +23,9 @@ import org.apache.commons.logging.LogFactory; import org.wso2.carbon.device.mgt.common.configuration.mgt.ConfigurationEntry; import org.wso2.carbon.device.mgt.common.configuration.mgt.ConfigurationManagementException; import org.wso2.carbon.device.mgt.common.configuration.mgt.PlatformConfiguration; -import org.wso2.carbon.device.mgt.jaxrs.service.api.DeviceTypeManagementService; +import org.wso2.carbon.device.mgt.jaxrs.service.api.ConfigurationManagementService; import org.wso2.carbon.device.mgt.jaxrs.util.DeviceMgtAPIUtils; import org.wso2.carbon.device.mgt.jaxrs.util.MDMAppConstants; -import org.wso2.carbon.device.mgt.jaxrs.util.ResponsePayload; import org.wso2.carbon.policy.mgt.core.util.PolicyManagerUtil; import javax.ws.rs.*; @@ -34,40 +33,30 @@ import javax.ws.rs.core.Response; import java.util.ArrayList; import java.util.List; -@Path("/device-types") -public class DeviceTypeManagementServiceImpl implements DeviceTypeManagementService { +@Path("/configuration") +public class ConfigurationServiceImpl implements ConfigurationManagementService { - private static final Log log = LogFactory.getLog(DeviceTypeManagementServiceImpl.class); - - @GET - @Override - public Response getTypes() { - return null; - } + private static final Log log = LogFactory.getLog(ConfigurationServiceImpl.class); @POST - @Path("/{type}/configuration") @Override - public Response saveConfiguration(@PathParam("type") String type, PlatformConfiguration config) { - ResponsePayload responseMsg = new ResponsePayload(); + public Response saveConfiguration(PlatformConfiguration config) { try { DeviceMgtAPIUtils.getPlatformConfigurationManagementService().saveConfiguration(config, MDMAppConstants.RegistryConstants.GENERAL_CONFIG_RESOURCE_PATH); //Schedule the task service DeviceMgtAPIUtils.scheduleTaskService(DeviceMgtAPIUtils.getNotifierFrequency(config)); - return Response.status(Response.Status.OK).entity("Platform configuration of device type '" + type + - "' has successfully been saved").build(); + return Response.status(Response.Status.OK).entity("Platform configuration successfully saved.").build(); } catch (ConfigurationManagementException e) { - String msg = "Error occurred while saving the platform configuration of device type '" + type + "'"; + String msg = "Error occurred while saving the platform configuration."; log.error(msg, e); return javax.ws.rs.core.Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(msg).build(); } } @GET - @Path("/{type}/configuration") @Override - public Response getConfiguration(@PathParam("type") String type) { + public Response getConfiguration() { String msg; try { PlatformConfiguration config = DeviceMgtAPIUtils.getPlatformConfigurationManagementService(). @@ -84,26 +73,24 @@ public class DeviceTypeManagementServiceImpl implements DeviceTypeManagementServ config.setConfiguration(configList); return Response.status(Response.Status.OK).entity(config).build(); } catch (ConfigurationManagementException e) { - msg = "Error occurred while retrieving the configuration of device type '" + type + "'"; + msg = "Error occurred while retrieving the configurations."; log.error(msg, e); return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(msg).build(); } } @PUT - @Path("/{type}/configuration") @Override - public Response updateConfiguration(@PathParam("type") String type, PlatformConfiguration config) { - ResponsePayload responseMsg = new ResponsePayload(); + public Response updateConfiguration(PlatformConfiguration config) { try { DeviceMgtAPIUtils.getPlatformConfigurationManagementService().saveConfiguration(config, MDMAppConstants.RegistryConstants.GENERAL_CONFIG_RESOURCE_PATH); //Schedule the task service DeviceMgtAPIUtils.scheduleTaskService(DeviceMgtAPIUtils.getNotifierFrequency(config)); - return Response.status(Response.Status.CREATED).entity("Configuration of device type '" + type + - "' has successfully been updated").build(); + return Response.status(Response.Status.CREATED) + .entity("Configuration has successfully been updated").build(); } catch (ConfigurationManagementException e) { - String msg = "Error occurred while updating the configuration of device type '" + type + "'"; + String msg = "Error occurred while updating the configuration."; log.error(msg, e); return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(msg).build(); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/PolicyManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/PolicyManagementServiceImpl.java index 288740489d0..2225e6069ad 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/PolicyManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/PolicyManagementServiceImpl.java @@ -39,6 +39,7 @@ import javax.ws.rs.*; import javax.ws.rs.core.Response; import java.util.List; +@Path("/policies") public class PolicyManagementServiceImpl implements PolicyManagementService { private static final Log log = LogFactory.getLog(PolicyManagementServiceImpl.class); @@ -101,6 +102,9 @@ public class PolicyManagementServiceImpl implements PolicyManagementService { try { PolicyAdministratorPoint policyAdministratorPoint = policyManagementService.getPAP(); policies = policyAdministratorPoint.getPolicies(); + if (policies == null || policies.size() == 0) { + return Response.status(Response.Status.NOT_FOUND).entity("No policies found.").build(); + } } catch (PolicyManagementException e) { String msg = "Error occurred while retrieving all available policies"; log.error(msg, e); @@ -118,6 +122,9 @@ public class PolicyManagementServiceImpl implements PolicyManagementService { try { PolicyAdministratorPoint policyAdministratorPoint = policyManagementService.getPAP(); policy = policyAdministratorPoint.getPolicy(id); + if (policy == null) { + return Response.status(Response.Status.NOT_FOUND).entity("Policy not found.").build(); + } } catch (PolicyManagementException e) { String msg = "Error occurred while retrieving policy corresponding to the id '" + id + "'"; log.error(msg, e); @@ -168,7 +175,7 @@ public class PolicyManagementServiceImpl implements PolicyManagementService { return Response.status(Response.Status.OK).entity("Policies have been successfully deleted").build(); } else { //TODO:Check of this logic is correct - return Response.status(Response.Status.BAD_REQUEST).entity("Policy doesn't exist").build(); + return Response.status(Response.Status.NOT_FOUND).entity("Policy doesn't exist").build(); } } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/RoleManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/RoleManagementServiceImpl.java index 53e81196c59..b8568198db5 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/RoleManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/RoleManagementServiceImpl.java @@ -48,6 +48,9 @@ public class RoleManagementServiceImpl implements RoleManagementService { List filteredRoles; try { filteredRoles = getRolesFromUserStore(); + if (filteredRoles == null || filteredRoles.size() == 0) { + return Response.status(Response.Status.NOT_FOUND).entity("No roles found.").build(); + } } catch (UserStoreException e) { String msg = "Error occurred while retrieving roles from the underlying user stores"; log.error(msg, e); @@ -82,6 +85,9 @@ public class RoleManagementServiceImpl implements RoleManagementService { filteredRoles.add(role); } } + if (filteredRoles == null || filteredRoles.size() == 0) { + return Response.status(Response.Status.NOT_FOUND).entity("No roles found.").build(); + } return Response.status(Response.Status.OK).entity(filteredRoles).build(); } @@ -110,6 +116,9 @@ public class RoleManagementServiceImpl implements RoleManagementService { filteredRoles.add(role); } } + if (filteredRoles == null || filteredRoles.size() == 0) { + return Response.status(Response.Status.NOT_FOUND).entity("No roles found.").build(); + } return Response.status(Response.Status.OK).entity(filteredRoles).build(); } @@ -126,6 +135,10 @@ public class RoleManagementServiceImpl implements RoleManagementService { } final UserRealmProxy userRealmProxy = new UserRealmProxy(userRealmCore); rolePermissions = this.getUIPermissionNode(roleName, userRealmProxy); + if (rolePermissions == null) { + return Response.status(Response.Status.NOT_FOUND).entity("No permissions found for the role '" + + roleName + "'").build(); + } return Response.status(Response.Status.OK).entity(rolePermissions).build(); } catch (UserAdminException e) { String msg = "Error occurred while retrieving the permissions of role '" + roleName + "'"; @@ -188,6 +201,10 @@ public class RoleManagementServiceImpl implements RoleManagementService { String[] permListAr = new String[permList.size()]; roleWrapper.setPermissions(permList.toArray(permListAr)); } + if (roleWrapper == null) { + return Response.status(Response.Status.NOT_FOUND).entity("No roles found for the role name '" + + roleName + ".").build(); + } } catch (UserStoreException | UserAdminException e) { String msg = "Error occurred while retrieving the user role '" + roleName + "'"; log.error(msg, e); diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/UserManagementServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/UserManagementServiceImpl.java index a74dededc23..ba82720bc98 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/UserManagementServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/UserManagementServiceImpl.java @@ -175,6 +175,10 @@ public class UserManagementServiceImpl implements UserManagementService { if (log.isDebugEnabled()) { log.debug("User by username: " + username + " was found."); } + if (user == null) { + return Response.status(Response.Status.NOT_FOUND).entity("User by username '" + username + "' " + + "doesn't exist").build(); + } return Response.status(Response.Status.OK).entity(user).build(); } else { // Outputting debug message upon trying to remove non-existing user @@ -182,7 +186,7 @@ public class UserManagementServiceImpl implements UserManagementService { log.debug("User by username: " + username + " does not exist."); } // returning response with bad request state - return Response.status(Response.Status.BAD_REQUEST).entity( + return Response.status(Response.Status.NOT_FOUND).entity( "User by username: " + username + " does not exist").build(); } } catch (UserStoreException e) { @@ -196,7 +200,6 @@ public class UserManagementServiceImpl implements UserManagementService { @Path("/{username}") @Override public Response updateUser(@PathParam("username") String username, UserWrapper userWrapper) { - ResponsePayload responsePayload = new ResponsePayload(); try { UserStoreManager userStoreManager = DeviceMgtAPIUtils.getUserStoreManager(); if (userStoreManager.isExistingUser(userWrapper.getUsername())) { @@ -233,21 +236,16 @@ public class UserManagementServiceImpl implements UserManagementService { log.debug("User by username: " + userWrapper.getUsername() + " was successfully updated."); } // returning response with success state - responsePayload.setStatusCode(HttpStatus.SC_CREATED); - responsePayload.setMessageFromServer("User by username: " + userWrapper.getUsername() + - " was successfully updated."); - return Response.status(Response.Status.CREATED).entity(responsePayload).build(); + return Response.status(Response.Status.CREATED).entity("User by username '" + userWrapper.getUsername() + + "' was successfully updated.").build(); } else { if (log.isDebugEnabled()) { log.debug("User by username: " + userWrapper.getUsername() + " doesn't exists. Therefore, request made to update user was refused."); } - // returning response with bad request state - responsePayload.setStatusCode(HttpStatus.SC_CONFLICT); - responsePayload. - setMessageFromServer("User by username: " + userWrapper.getUsername() + - " doesn't exists. Therefore, request made to update user was refused."); - return Response.status(Response.Status.CONFLICT).entity(responsePayload).build(); + return Response.status(Response.Status.CONFLICT).entity("User by username: " + + userWrapper.getUsername() + " doesn't exists. Therefore, request made to update user was " + + "refused.").build(); } } catch (UserStoreException | UnsupportedEncodingException e) { String msg = "Exception in trying to update user by username: " + userWrapper.getUsername(); @@ -294,7 +292,7 @@ public class UserManagementServiceImpl implements UserManagementService { log.debug("User by username: " + username + " does not exist for removal."); } // returning response with bad request state - return Response.status(Response.Status.BAD_REQUEST).entity("User by username: " + username + + return Response.status(Response.Status.NOT_FOUND).entity("User by username: " + username + " does not exist for removal.").build(); } } catch (UserStoreException e) { @@ -318,7 +316,7 @@ public class UserManagementServiceImpl implements UserManagementService { if (log.isDebugEnabled()) { log.debug("User by username: " + username + " does not exist for role retrieval."); } - return Response.status(Response.Status.BAD_REQUEST).entity("User by username: " + username + + return Response.status(Response.Status.NOT_FOUND).entity("User by username: " + username + " does not exist for role retrieval.").build(); } } catch (UserStoreException e) { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/DeviceManagementAdminServiceImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/DeviceManagementAdminServiceImpl.java index 9efc01120b6..73520f02b17 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/DeviceManagementAdminServiceImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/impl/admin/DeviceManagementAdminServiceImpl.java @@ -25,10 +25,7 @@ import org.wso2.carbon.device.mgt.common.DeviceManagementException; import org.wso2.carbon.device.mgt.jaxrs.service.api.admin.DeviceManagementAdminService; import org.wso2.carbon.device.mgt.jaxrs.util.DeviceMgtAPIUtils; -import javax.ws.rs.Consumes; -import javax.ws.rs.Path; -import javax.ws.rs.Produces; -import javax.ws.rs.QueryParam; +import javax.ws.rs.*; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import java.util.List; @@ -41,6 +38,7 @@ public class DeviceManagementAdminServiceImpl implements DeviceManagementAdminSe private static final Log log = LogFactory.getLog(DeviceManagementAdminServiceImpl.class); @Override + @GET public Response getDevicesByName(@QueryParam("name") String name, @QueryParam("tenant-domain") String tenantDomain) { List devices; try { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/webapp/WEB-INF/cxf-servlet.xml b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/webapp/WEB-INF/cxf-servlet.xml index d78576f689d..6299d10ff4d 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/webapp/WEB-INF/cxf-servlet.xml +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/webapp/WEB-INF/cxf-servlet.xml @@ -64,7 +64,7 @@ - +