Improving swagger annotations of device management admin API

components/mobile-plugins/android-plugin/org.wso2.carbon.device.mgt.mobile.android.api/src/main/java/org/wso2/carbon/mdm/services/android/services/DeviceManagementService.java

@@ -18,10 +18,7 @@
  */
 package org.wso2.carbon.mdm.services.android.services;
 
-import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.*;
-import io.swagger.annotations.ApiParam;
-import io.swagger.annotations.ApiResponse;
-import io.swagger.annotations.ApiResponses;
 import org.wso2.carbon.device.mgt.common.Device;
 import org.wso2.carbon.device.mgt.common.app.mgt.Application;
 import org.wso2.carbon.device.mgt.common.operation.mgt.Operation;
@@ -31,6 +28,8 @@ import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 import java.util.List;
 
+@Api(value = "Android Device Management API",
+        description = "This carries all the resources related to Android device management functionalities")
 @Path("/devices")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
@@ -41,15 +40,18 @@ public interface DeviceManagementService {
     @ApiOperation(
             consumes = MediaType.APPLICATION_JSON,
             httpMethod = "PUT",
-            value = "Updating an ApplicationList",
+            value = "Update the application list of a device"
-            notes = "Update application list in server side."
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 202, message = "Device information has modified successfully"),
+            @ApiResponse(code = 200, message = "OK. \n " +
-            @ApiResponse(code = 500, message = "Error occurred while modifying the application list")
+                    "Application list of the device has successfully been updated"),
+            @ApiResponse(code = 204, message = "No Content. \n Application list of the device has not been updated"),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Sever error occurred while modifying the application list")
     })
-    Response updateApplicationList(@ApiParam(name = "id", value = "deviceIdentifier") @PathParam("id") String id,
+    Response updateApplicationList(@ApiParam(name = "id", value = "Device Identifier") @PathParam("id") String id,
-                                   @ApiParam(name = "applications", value = "updatable applications")
+                                   @ApiParam(name = "applications", value = "List of applications that need to be " +
+                                           "persisted against the device")
                                    List<Application> applications);
 
     @GET
@@ -58,17 +60,34 @@ public interface DeviceManagementService {
             consumes = MediaType.APPLICATION_JSON,
             produces = MediaType.APPLICATION_JSON,
             httpMethod = "PUT",
-            value = "Getting Pending Android Device Operations",
+            value = "Get the operation list pending for the device",
             responseContainer = "List",
             notes = "The Android agent communicates with the server to get the operations that are queued up " +
-                    "at the server end for a given device using this REST API",
+                    "at the server end for a given device using via this particular resource",
             response = Operation.class)
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "List of pending operations"),
+            @ApiResponse(code = 200, message = "OK. \n List of pending operations of the device is returned",
-            @ApiResponse(code = 500, message = "Issue in retrieving operation management service instance")
+                    responseHeaders = {
+                            @ResponseHeader(name = "Content-Type", description = "The content type of the body"),
+                            @ResponseHeader(name = "ETag", description = "Entity Tag of the response resource.\n" +
+                                    "Used by caches, or in conditional requests."),
+                            @ResponseHeader(name = "Last-Modified",
+                                    description = "Date and time the resource has been modified the last time.\n" +
+                                            "Used by caches, or in conditional requests.")}),
+            @ApiResponse(code = 303, message = "See Other. \n " +
+                    "Source can be retrieved from the URL specified at the Location header.",
+                    responseHeaders = {
+                            @ResponseHeader(name = "Location", description = "The Source URL of the document.")}),
+            @ApiResponse(code = 304, message = "Not Modified. \n " +
+                    "Empty body because the client already has the latest version of the requested resource."),
+            @ApiResponse(code = 400, message = "Bad Request. \n Invalid request or validation error."),
+            @ApiResponse(code = 404, message = "Not Found. \n Requested device not found."),
+            @ApiResponse(code = 406, message = "Not Acceptable. \n The requested media type is not supported."),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Server error occurred while retrieving the pending operation list of the device.")
     })
     Response getPendingOperations(
-            @ApiParam(name = "id", value = "DeviceIdentifier") @PathParam("id") String id,
+            @ApiParam(name = "id", value = "Device Identifier") @PathParam("id") String id,
             @ApiParam(name = "resultOperations", value = "Device Operation Status")
             List<? extends Operation> resultOperations);
 
@@ -76,15 +95,20 @@ public interface DeviceManagementService {
     @ApiOperation(
             consumes = MediaType.APPLICATION_JSON,
             httpMethod = "POST",
-            value = "Registering an Android Device",
+            value = "Register an Android Device",
             notes = "When carrying out device registration via an Android device, you need to initially install" +
                     " an Android Agent on the device, before being able to register the device with WSO2 EMM. Instead," +
                     " you can use this REST API to register an Android device with WSO2 EMM, without having to install" +
                     " an Android Agent on the respective device"
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Device enrollment succeeded"),
+            @ApiResponse(code = 201, message = "Created. \n Device has successfully been enrolled. Location header " +
-            @ApiResponse(code = 500, message = "Device enrollment failed"),
+                    "contains URL of newly enrolled device",
+                    responseHeaders = {
+                            @ResponseHeader(name = "Location", description = "URL of the device enrolled")}),
+            @ApiResponse(code = 400, message = "Bad Request. \n Invalid request or validation error."),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Server error occurred while enrolling the device."),
     })
     Response enrollDevice(@ApiParam(name = "device", value = "Device Information to be enroll") Device device);
 
@@ -96,10 +120,19 @@ public interface DeviceManagementService {
             notes = "Use this REST API to retrieve the registration status of an Android device"
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Device has already enrolled"),
+            @ApiResponse(code = 200, message = "Device has already enrolled",
-            @ApiResponse(code = 404, message = "Device not found")
+                    responseHeaders = {
+                            @ResponseHeader(name = "Content-Type", description = "The content type of the body"),
+                            @ResponseHeader(name = "ETag", description = "Entity Tag of the response resource.\n" +
+                                    "Used by caches, or in conditional requests."),
+                            @ResponseHeader(name = "Last-Modified",
+                                    description = "Date and time the resource has been modified the last time.\n" +
+                                            "Used by caches, or in conditional requests.")}),
+            @ApiResponse(code = 404, message = "Not Found. \n Requested device not found."),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Server error occurred while retrieving the enrollment status of the device."),
     })
-    Response isEnrolled(@ApiParam(name = "id", value = "DeviceIdentifier") @PathParam("id") String id);
+    Response isEnrolled(@ApiParam(name = "id", value = "Device Identifier") @PathParam("id") String id);
 
     @PUT
     @Path("/{id}")
@@ -109,10 +142,22 @@ public interface DeviceManagementService {
             notes = "Use this REST API to update the registration details of an Android device"
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Device enrollment has updated successfully"),
+            @ApiResponse(code = 200, message = "OK. \n Device enrollment has been updated successfully",
-            @ApiResponse(code = 404, message = "Device not found for enrollment")
+                    responseHeaders = {
+                            @ResponseHeader(name = "Location", description = "The URL of the updated device."),
+                            @ResponseHeader(name = "Content-Type", description = "The content type of the body"),
+                            @ResponseHeader(name = "ETag", description = "Entity Tag of the response resource.\n" +
+                                    "Used by caches, or in conditional requests."),
+                            @ResponseHeader(name = "Last-Modified",
+                                    description = "Date and time the resource has been modified the last time.\n" +
+                                            "Used by caches, or in conditional requests.")}),
+            @ApiResponse(code = 204, message = "No Content. \n Enrollment of the device has not been updated"),
+            @ApiResponse(code = 400, message = "Bad Request. \n Invalid request or validation error."),
+            @ApiResponse(code = 404, message = "Not Found. \n Resource to be deleted does not exist."),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Server error occurred while modifying the current enrollment of the device.")
     })
-    Response modifyEnrollment(@ApiParam(name = "id", value = "DeviceIdentifier") @PathParam("id") String id,
+    Response modifyEnrollment(@ApiParam(name = "id", value = "Device Identifier") @PathParam("id") String id,
                               @ApiParam(name = "device", value = "Device information to be modify") Device device);
 
     @DELETE
@@ -120,12 +165,14 @@ public interface DeviceManagementService {
     @ApiOperation(
             httpMethod = "DELETE",
             value = "Un-registering an Android Device",
-            notes = "Use this REST API to unregister a specific Android device"
+            notes = "Use this REST API to un-register a specific Android device"
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Device has removed successfully"),
+            @ApiResponse(code = 200, message = "OK. \n Device has successfully been dis-enrolled"),
-            @ApiResponse(code = 404, message = "Device not found")
+            @ApiResponse(code = 404, message = "Not Found. \n Device requested to be dis-enrolled does not exist."),
+            @ApiResponse(code = 500, message = "Internal Server Error. \n " +
+                    "Server error occurred while dis-enrolling the the device."),
     })
-    Response disEnrollDevice(@ApiParam(name = "id", value = "DeviceIdentifier") @PathParam("id") String id);
+    Response disEnrollDevice(@ApiParam(name = "id", value = "Device Identifier") @PathParam("id") String id);
 
 }