From b407797ab081cf291bf07bcdeda02ad584faea29 Mon Sep 17 00:00:00 2001 From: Madhawa Date: Thu, 12 May 2016 20:16:52 +0530 Subject: [PATCH] added swagger annotation to the interfaces --- .../device/mgt/jaxrs/api/Certificate.java | 76 +++++- .../device/mgt/jaxrs/api/Configuration.java | 47 +++- .../carbon/device/mgt/jaxrs/api/Device.java | 93 ++++--- .../mgt/jaxrs/api/DeviceInformation.java | 43 +++- .../mgt/jaxrs/api/DeviceNotification.java | 66 ++++- .../device/mgt/jaxrs/api/DeviceSearch.java | 21 +- .../carbon/device/mgt/jaxrs/api/User.java | 243 ++++++++++++++++-- .../mgt/jaxrs/api/impl/CertificateImpl.java | 2 +- 8 files changed, 527 insertions(+), 64 deletions(-) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java index 3676479cae..8bfcd31f66 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java @@ -19,10 +19,18 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.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.certificate.mgt.core.dto.CertificateResponse; +import org.wso2.carbon.device.mgt.common.PaginationResult; import org.wso2.carbon.device.mgt.jaxrs.api.common.MDMAPIException; +import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload; import org.wso2.carbon.device.mgt.jaxrs.beans.EnrollmentCertificate; import javax.ws.rs.*; +import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; /** @@ -43,8 +51,21 @@ public interface Certificate { */ @POST @Path("saveCertificate") + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "POST", + value = "Adding an SSL Certificate", + notes = "Add a new SSL certificate to the client end database", + response = MediaType.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Added successfully"), + @ApiResponse(code = 500, message = "Error occurred while saving the certificate") + }) Response saveCertificate(@HeaderParam("Accept") String acceptHeader, - EnrollmentCertificate[] enrollmentCertificates); + @ApiParam(name = "enrollmentCertificates", value = "certificate with serial, " + + "pem and tenant id", required = true) EnrollmentCertificate[] + enrollmentCertificates); /** * Get a certificate when the serial number is given. @@ -54,7 +75,21 @@ public interface Certificate { */ @GET @Path("{serialNumber}") + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "GET", + value = "Getting Details of an SSL Certificate", + notes = "Get the client side SSL certificate details", + response = CertificateResponse.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 400, message = "Notification status updated successfully"), + @ApiResponse(code = 500, message = "Error occurred while converting PEM file to X509Certificate") + }) Response getCertificate(@HeaderParam("Accept") String acceptHeader, + @ApiParam(name = "serialNumber", value = "Provide the serial number of the " + + "certificate that you wish to get the details of", required = true) @PathParam("serialNumber") String serialNumber); /** @@ -67,13 +102,46 @@ public interface Certificate { */ @GET @Path("paginate") + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "GET", + value = "Getting the Certificate Details in a Paginated Manner", + notes = "You will have many certificates used for mutual SSL. In a situation where you wish to " + + "view all the certificate details, it is not feasible to show all the details on one " + + "page therefore the details are paginated", + response = PaginationResult.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 400, message = "Invalid start index"), + @ApiResponse(code = 400, message = "Invalid length value"), + @ApiResponse(code = 500, message = "Error occurred while fetching all certificates") + }) Response getAllCertificates(@HeaderParam("Accept") String acceptHeader, - @QueryParam("start") int startIndex, @QueryParam("length") int length) - throws MDMAPIException; + @ApiParam(name = "start", + value = "Provide the starting pagination index as the value", required = true) + @QueryParam("start") int startIndex, + @ApiParam(name = "length", value = "Provide how many certificate details you" + + " require from the starting pagination index as the value", + required = true) @QueryParam("length") int length) throws MDMAPIException; @DELETE @Path("{serialNumber}") + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "DELETE", + value = "Deleting an SSL Certificate", + notes = "Delete an SSL certificate that's on the client end", + response = boolean.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 400, message = "Invalid start index"), + @ApiResponse(code = 500, message = "Error when deleting the certificate" + ) }) Response removeCertificate(@HeaderParam("Accept") String acceptHeader, - @PathParam("serialNumber") String serialNumber) throws MDMAPIException; + @ApiParam(name = "serialNumber", value = "Provide the serial number of the " + + "certificate that you wish to delete", required = true) + @PathParam("serialNumber") String serialNumber) throws MDMAPIException; } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java index a1602eada3..c7bc7759cf 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java @@ -19,9 +19,15 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.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.device.mgt.common.configuration.mgt.TenantConfiguration; +import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload; import javax.ws.rs.*; +import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; /** @@ -35,12 +41,49 @@ import javax.ws.rs.core.Response; public interface Configuration { @POST - Response saveTenantConfiguration(TenantConfiguration 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", + response = ResponsePayload.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Tenant configuration saved successfully"), + @ApiResponse(code = 500, message = "Error occurred while saving the tenant configuration") + }) + Response saveTenantConfiguration(@ApiParam(name = "configuration", value = "The required properties to " + + "update the platform configurations the as the value", + required = true) TenantConfiguration configuration); @GET + @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 = TenantConfiguration.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the tenant configuration") + }) Response getConfiguration(); @PUT - Response updateConfiguration(TenantConfiguration 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", + response = ResponsePayload.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Tenant configuration updated successfully"), + @ApiResponse(code = 500, message = "Error occurred while updating the tenant configuration") + }) + Response updateConfiguration(@ApiParam(name = "configuration", value = "The required properties to update" + + " the platform configurations the as the value", + required = true) TenantConfiguration configuration); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java index e3d3d9e745..9710e6f426 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java @@ -20,6 +20,7 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.*; import org.wso2.carbon.device.mgt.common.EnrolmentInfo; +import org.wso2.carbon.device.mgt.core.dto.DeviceType; import javax.ws.rs.*; import javax.ws.rs.core.MediaType; @@ -43,22 +44,37 @@ public interface Device { consumes = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON, httpMethod = "GET", - value = "Returns the set of devices that matches a given device type, user, role, " - + "enrollment status, ownership type", - notes = "Returns 500 if the operation fails", - response = Device.class, + value = "Returns device list", + notes = "Returns the set of devices that matches a given device type, user, role, " + + "enrollment status, ownership type", + response = org.wso2.carbon.device.mgt.common.Device.class, responseContainer = "List") - @ApiResponses(value = { @ApiResponse(code = 200, message = "List of Devices"), - @ApiResponse(code = 500, message = "Server Error") }) - Response getAllDevices( - @ApiParam(name = "type", value = "Provide the device type, such as ios, android or windows", required = true) @QueryParam("type") String type, - @ApiParam(name = "user", value = "Get the details of the devices registered to a user by providing the user name", required = true) @QueryParam("user") String user, - @ApiParam(name = "role", value = "Get the details of the devices registered to a specific role by providing the role name", required = true) @QueryParam("role") String role, - @ApiParam(name = "status", value = "Provide the device status details, such as active or inactive", required = true) @QueryParam("status") EnrolmentInfo.Status status, - @ApiParam(name = "start", value = "Provide the starting pagination index", required = true) @QueryParam("start") int startIdx, - @ApiParam(name = "length", value = "Provide how many device details you require from the starting pagination index", required = true) @QueryParam("length") int length, - @ApiParam(name = "device-name", value = "Provide the name of a registered device and receive the specified device details", required = true) @QueryParam("device-name") String deviceName, - @ApiParam(name = "ownership", value = "Provide the device ownership type and receive the specific device details", required = true) @QueryParam("ownership") EnrolmentInfo.OwnerShip ownership); + @ApiResponses(value = { + @ApiResponse(code = 200, message = "List of Devices"), + @ApiResponse(code = 500, message = "Error occurred while fetching the device list") + }) + Response getAllDevices(@ApiParam(name = "type", value = "Provide the device type, such as ios, android or" + + " windows", required = true) @QueryParam("type") String type, + @ApiParam(name = "user", value = "Get the details of the devices registered to a " + + "user by providing the user name", required = true) @QueryParam("user") + String user, + @ApiParam(name = "role", value = "Get the details of the devices registered to a " + + "specific role by providing the role name", required = true) + @QueryParam("role") String role, + @ApiParam(name = "status", value = "Provide the device status details, such as " + + "active or inactive", required = true) @QueryParam("status") + EnrolmentInfo.Status status, + @ApiParam(name = "start", value = "Provide the starting pagination index", + required = true) @QueryParam("start") int startIdx, + @ApiParam(name = "length", value = "Provide how many device details you require " + + "from the starting pagination index", required = true) + @QueryParam("length") int length, + @ApiParam(name = "device-name", value = "Provide the name of a registered device " + + "and receive the specified device details", required = true) + @QueryParam("device-name") String deviceName, + @ApiParam(name = "ownership", value = "Provide the device ownership type and " + + "receive the specific device details", required = true) + @QueryParam("ownership") EnrolmentInfo.OwnerShip ownership); /** * Fetch device details for a given device type and device Id. @@ -66,14 +82,6 @@ public interface Device { * @return Device wrapped inside Response */ @GET - @ApiOperation( - produces = MediaType.APPLICATION_JSON, - httpMethod = "GET", - value = "Fetch device details for a given device type and device Id", - notes = "Returns 500 if the operation fails", - response = Device.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "Matching Device"), - @ApiResponse(code = 500, message = "Server Error") }) @Path("view") @Produces({ MediaType.APPLICATION_JSON }) Response getDevice(@QueryParam("type") String type, @QueryParam("id") String id); @@ -104,14 +112,16 @@ public interface Device { * @return device count */ @GET + @Path("count") @ApiOperation( httpMethod = "GET", - value = "Returns the current device count", - notes = "Returns 500 if the operation fails", + value = "Getting the Device Count", + notes = "Get the number of devices that are registered with WSO2 EMM.", response = Integer.class) - @ApiResponses(value = { @ApiResponse(code = 200, message = "Device count"), - @ApiResponse(code = 500, message = "Server Error") }) - @Path("count") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Device count"), + @ApiResponse(code = 500, message = "Error occurred while fetching the device count") + }) Response getDeviceCount(); /** @@ -123,8 +133,21 @@ public interface Device { */ @GET @Path("name/{name}/{tenantDomain}") - Response getDevicesByName(@PathParam("name") String deviceName, - @PathParam("tenantDomain") String tenantDomain); + @ApiOperation( + httpMethod = "GET", + value = "Get the device details of a specific device via the REST API", + notes = "Get the device details of a specific device", + response = DeviceType.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "List of devices"), + @ApiResponse(code = 500, message = "Error occurred while fetching the devices list of device name") + }) + Response getDevicesByName(@ApiParam(name = "name", value = "The name of the device or windows", + required = true) @PathParam("name") String deviceName, + @ApiParam(name = "tenantDomain", value = "Tenant domain name. The default " + + "tenant domain of WSO2 EMM is carbon.super", required = true) + @PathParam("tenantDomain") String tenantDomain); /** * Get the list of available device types. @@ -133,6 +156,16 @@ public interface Device { */ @GET @Path("types") + @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") }) Response getDeviceTypes(); /** diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java index 5cff26e61f..d55477eb07 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java @@ -19,10 +19,18 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.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.device.mgt.common.device.details.DeviceInfo; +import org.wso2.carbon.device.mgt.common.device.details.DeviceLocation; +import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam; +import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; /** @@ -34,10 +42,41 @@ public interface DeviceInformation { @GET @Path("{type}/{id}") - Response getDeviceInfo(@PathParam("type") String type, @PathParam("id") String id); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Get device information", + notes = "This will return device information such as CPU usage, memory usage etc.", + response = DeviceInfo.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = ""), + @ApiResponse(code = 400, message = ""), + @ApiResponse(code = 400, message = ""), + @ApiResponse(code = 500, message = "Internal Server Error") + }) + Response getDeviceInfo(@ApiParam(name = "type", value = "Provide the device type, such as ios, android " + + "or windows", required = true) @PathParam("type") String type, + @ApiParam(name = "id", value = "Provide the device identifier", required = true) + @PathParam("id") String id); @GET @Path("location/{type}/{id}") - Response getDeviceLocation(@PathParam("type") String type, @PathParam("id") String id); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Get the device location", + notes = "This will return the device location including latitude and longitude as well the " + + "physical address", + response = DeviceLocation.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = ""), + @ApiResponse(code = 400, message = ""), + @ApiResponse(code = 400, message = ""), + @ApiResponse(code = 500, message = "Internal Server Error") + }) + Response getDeviceLocation(@ApiParam(name = "type", value = "Provide the device type, such as ios, " + + "android or windows", required = true) @PathParam("type") String type, + @ApiParam(name = "id", value = "Provide the device identifier", + required = true) @PathParam("id") String id); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java index 62c2bcdaa3..f17e584051 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java @@ -19,7 +19,12 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.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.device.mgt.common.notification.mgt.Notification; +import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload; import javax.ws.rs.Consumes; import javax.ws.rs.GET; @@ -28,6 +33,7 @@ import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; +import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; /** @@ -41,18 +47,72 @@ import javax.ws.rs.core.Response; public interface DeviceNotification { @GET + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "GET", + value = "Getting all Device Notification Details", + notes = "Get the details of all notifications that were pushed to the device in WSO2 EMM using " + + "this REST API", + response = Notification.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "List of Notifications"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list") + }) Response getNotifications(); @GET @Path("{status}") - Response getNotificationsByStatus(@PathParam("status") Notification.Status status); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "GET", + 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", + response = Notification.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "List of Notifications"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the notification list") + }) + Response getNotificationsByStatus(@ApiParam(name = "status", value = "Provide the notification status as" + + " the value for {status}", required = true) + @PathParam("status") Notification.Status status); @PUT @Path("{id}/{status}") - Response updateNotificationStatus(@PathParam("id") int id, - @PathParam("status") Notification.Status status); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + 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", + response = ResponsePayload.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Notification status updated successfully"), + @ApiResponse(code = 500, message = "Error occurred while updating notification status") + }) + Response updateNotificationStatus( @ApiParam(name = "id", value = "Provide the ID of the notification" + + " you wish you update", required = true) @PathParam("id") int id, + @ApiParam(name = "status", value = "Provide the notification status as" + + " the value", required = true) @PathParam("status") + Notification.Status status); @POST + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "POST", + value = "Sending a Device Notification", + notes = "Notify users on device operation failures and other information using this REST API", + response = ResponsePayload.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "NNotification has added successfully"), + @ApiResponse(code = 500, message = "Error occurred while updating notification status") + }) Response addNotification(Notification notification); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java index ffb72fbebb..ec27086e36 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java @@ -19,9 +19,16 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.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.device.mgt.common.PaginationResult; +import org.wso2.carbon.device.mgt.common.device.details.DeviceWrapper; import org.wso2.carbon.device.mgt.common.search.SearchContext; import javax.ws.rs.GET; +import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; /** @@ -32,5 +39,17 @@ import javax.ws.rs.core.Response; public interface DeviceSearch { @GET - Response getDeviceInfo(SearchContext searchContext); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Advanced Search for Devices via the Console", + notes = "Carry out an advanced search via the EMM console", + response = DeviceWrapper.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 500, message = "Error occurred while searching the device information") + }) + Response getDeviceInfo(@ApiParam(name = "enrollmentCertificates", value = "List of search conditions", + required = true) SearchContext searchContext); } diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java index e55a2bcb32..6c5e45b7b9 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java @@ -19,6 +19,12 @@ package org.wso2.carbon.device.mgt.jaxrs.api; import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; +import org.apache.axis2.databinding.types.soapencoding.Integer; +import org.wso2.carbon.device.mgt.jaxrs.api.util.ResponsePayload; import org.wso2.carbon.device.mgt.jaxrs.beans.UserCredentialWrapper; import org.wso2.carbon.device.mgt.jaxrs.beans.UserWrapper; @@ -44,29 +50,111 @@ public interface User { @POST @Consumes({ MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON}) - Response addUser(UserWrapper userWrapper); + @ApiOperation( + 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") + @ApiResponses(value = { + @ApiResponse(code = 201, message = "Created"), + @ApiResponse(code = 500, message = "Exception in trying to add user by username: 'username'") + }) + Response addUser(@ApiParam(name = "userWrapper", value = "Includes the required properties to add a user" + + " as the value", required = true) UserWrapper userWrapper); @GET @Path("view") @Produces({MediaType.APPLICATION_JSON}) - Response getUser(@QueryParam("username") String username); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Getting Details of a User", + notes = "If you wish to get the details of a specific user that is registered with WSO2 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'") + }) + Response getUser(@ApiParam(name = "username", value = "Provide the name of the user you wish to get the" + + " details of as the value", required = true) + @QueryParam("username") String username); @PUT @Consumes({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON}) - Response updateUser(UserWrapper userWrapper, @QueryParam("username") String username); + @ApiOperation( + consumes = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + produces = MediaType.APPLICATION_JSON + ", " + MediaType.APPLICATION_XML, + httpMethod = "PUT", + 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") + @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 = 500, message = "Exception in trying to update user by username: 'username'") + }) + Response updateUser(@ApiParam(name = "userWrapper", value = "Provide the name of the user you wish to get" + + " the details of as the value", required = true) UserWrapper userWrapper, + @ApiParam(name = "username", value = "Provide the name of the user you wish to get " + + "the details of as the value", required = true) + @QueryParam("username") String username); @DELETE @Produces({MediaType.APPLICATION_JSON}) - Response removeUser(@QueryParam("username") String username); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "DELETE", + value = "Deleting a User", + notes = "In a situation where an employee leaves the organization you will need to remove the" + + " user details from WSO2 EMM. In such situations you can use this REST API " + + "to remove a user", + response = ResponsePayload.class) + @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'") + }) + Response removeUser(@ApiParam(name = "username", value = "Provide the name of the user you wish to delete" + + " as the value for {username}", required = true) + @QueryParam("username") String username); @GET @Path("roles") @Produces({MediaType.APPLICATION_JSON}) - Response getRoles(@QueryParam("username") String username); + @ApiOperation( + 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", + 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'") + }) + Response getRoles(@ApiParam(name = "username", value = "Provide the user name of the user you wish to get" + + " the role details", required = true) @QueryParam("username") String username); @GET @Produces({MediaType.APPLICATION_JSON}) + @ApiOperation( + 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 " + + "using the REST API", + response = ResponsePayload.class) + @ApiResponses(value = { + @ApiResponse(code = 201, message = "All users were successfully retrieved"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users") + }) Response getAllUsers(); @GET @@ -76,41 +164,154 @@ public interface User { @GET @Path("view-users") - Response getAllUsersByUsername(@QueryParam("username") String userName); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Getting User Details by Searching via the User Name", + notes = "You will have 100+ users registered with WSO2 EMM. If you wish to retrieve the user " + + "details of a specific user, and you only remember part of the user's username, " + + "you are able to retrieve the user details by giving a character or a few characters " + + "in the username", + 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") + }) + Response getAllUsersByUsername(@ApiParam(name = "username", value = "Provide any user detail of the user" + + " as the value for {username} to retrieve the user details, such " + + "as email address, first name or last name", required = true) + @QueryParam("username") String userName); @GET @Path("users-by-username") - Response getAllUserNamesByUsername(@QueryParam("username") String userName); + @ApiOperation( + 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 " + + "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", + 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") + }) + Response getAllUserNamesByUsername(@ApiParam(name = "username", value = "Provide a character or a few " + + "character in the user name as the value for {username}", + required = true) @QueryParam("username") String userName); @POST @Path("email-invitation") @Produces({MediaType.APPLICATION_JSON}) - Response inviteExistingUsersToEnrollDevice(List usernames); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Sending Enrollment Invitations to Users", + notes = "Send the users a mail inviting them to download the EMM mobile application on their " + + "devices using this REST API") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Email invitation was successfully sent to user"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users") + }) + Response inviteExistingUsersToEnrollDevice(@ApiParam(name = "usernames", value = "List of the users to be" + + " invited as the ", required = true) + List usernames); @GET @Produces({MediaType.APPLICATION_JSON}) @Path("devices") - Response getAllDeviceOfUser(@QueryParam("username") String username, @QueryParam("start") int startIdx, - @QueryParam("length") int length); + @ApiOperation( + produces = MediaType.APPLICATION_JSON, + httpMethod = "GET", + value = "Getting Device Details of a User", + notes = "If you wish to get the details of the devices enrolled by a specific user, you can do " + + "so using this REST API", + response = org.wso2.carbon.device.mgt.common.Device.class, + responseContainer = "List") + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 500, message = "Device management error") + }) + Response getAllDeviceOfUser(@ApiParam(name = "username", value = "Provide the name of the user you wish " + + "to get the details", required = true) @QueryParam("username") + String username, + @ApiParam(name = "start", value = "Provide the starting pagination index", + required = true) @QueryParam("start") int startIdx, + @ApiParam(name = "length", value = "Provide how many device details you " + + "require from the starting pagination index", required = true) + @QueryParam("length") int length); @GET - @Path("count") + @Path("count") + @ApiOperation( + httpMethod = "GET", + value = "Getting the User Count", + notes = "Get the number of users in WSO2 EMM", + response = Integer.class) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "OK"), + @ApiResponse(code = 500, message = "Error occurred while retrieving the list of users that exist" + + " within the current tenant") + }) Response getUserCount(); @PUT - @Path("{roleName}/users") - @Produces({MediaType.APPLICATION_JSON}) + @Path("{roleName}/users") + @Produces({MediaType.APPLICATION_JSON}) Response updateRoles(@PathParam("username") String username, List userList); @POST - @Path("change-password") - @Consumes({MediaType.APPLICATION_JSON}) - @Produces({MediaType.APPLICATION_JSON}) - Response resetPassword(UserCredentialWrapper credentials); + @Path("change-password") + @Consumes({MediaType.APPLICATION_JSON}) + @Produces({MediaType.APPLICATION_JSON}) + @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", + response = UserCredentialWrapper.class) + @ApiResponses(value = { + @ApiResponse(code = 200, 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") + }) + Response resetPassword(@ApiParam(name = "credentials", value = "Include the required properties to change" + + " the user password as value", required = true) + UserCredentialWrapper credentials); @POST - @Path("reset-password") - @Consumes({MediaType.APPLICATION_JSON}) - @Produces({MediaType.APPLICATION_JSON}) - Response resetPasswordByAdmin(UserCredentialWrapper credentials); + @Path("reset-password") + @Consumes({MediaType.APPLICATION_JSON}) + @Produces({MediaType.APPLICATION_JSON}) + @ApiOperation( + consumes = MediaType.APPLICATION_JSON, + produces = MediaType.APPLICATION_JSON, + httpMethod = "POST", + value = "Resetting the User Password", + notes = "In a situation where you need to block a user from accessing their EMM profile, " + + "the EMM administrator is able to reset the password. This will change the user's " + + "password and the user will not be able to able to login to the account as he/she is " + + "not aware of the new password.", + response = UserCredentialWrapper.class) + @ApiResponses(value = { + @ApiResponse(code = 200, 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") + }) + Response resetPasswordByAdmin(@ApiParam(name = "credentials", value = "Include the required properties " + + "to change a user password as value", + 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/api/impl/CertificateImpl.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/impl/CertificateImpl.java index 76689a3899..de062241f9 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/impl/CertificateImpl.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/impl/CertificateImpl.java @@ -53,7 +53,7 @@ import java.util.List; @SuppressWarnings("NonJaxWsWebServices") @Produces({"application/json", "application/xml"}) @Consumes({ "application/json", "application/xml" }) -public class CertificateImpl implements Certificate{ +public class CertificateImpl implements Certificate { private static Log log = LogFactory.getLog(OperationImpl.class);