Adding Swagger to Android sense end-points

components/device-types/androidsense-plugin/org.wso2.carbon.device.mgt.iot.androidsense.api/src/main/java/org/wso2/carbon/device/mgt/iot/androidsense/service/impl/AndroidSenseService.java

@@ -19,14 +19,23 @@
 
 package org.wso2.carbon.device.mgt.iot.androidsense.service.impl;
 
-import io.swagger.annotations.SwaggerDefinition;
+import io.swagger.annotations.ApiOperation;
-import io.swagger.annotations.Info;
+import io.swagger.annotations.ApiParam;
-import io.swagger.annotations.ExtensionProperty;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import io.swagger.annotations.Extension;
+import io.swagger.annotations.ExtensionProperty;
+import io.swagger.annotations.Info;
+import io.swagger.annotations.ResponseHeader;
+import io.swagger.annotations.SwaggerDefinition;
 import io.swagger.annotations.Tag;
-import org.wso2.carbon.apimgt.annotations.api.Scope;
 
-import javax.ws.rs.*;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.Response;
 
 @SwaggerDefinition(
@@ -52,10 +61,57 @@ public interface AndroidSenseService {
      * @param deviceId The registered device Id.
      * @param keywords The key words to be sent. (Comma separated values)
      */
-    @Path("device/{deviceId}/words")
     @POST
-    @Scope(key = "device:android-sense:enroll", name = "", description = "")
+    @Path("device/{deviceId}/words")
-    Response sendKeyWords(@PathParam("deviceId") String deviceId, @QueryParam("keywords") String keywords);
+    @ApiOperation(
+            httpMethod = "POST",
+            value = "End point to send the key words to the device",
+            notes = "",
+            tags = "android_sense",
+            extensions = {
+                    @Extension(properties = {
+                            @ExtensionProperty(name = "", value = "perm:android-sense:enroll")
+                    })
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    code = 200,
+                    message = "OK.",
+                    response = Response.class,
+                    responseHeaders = {
+                            @ResponseHeader(
+                                    name = "Content-Type",
+                                    description = "The content type of the body"),
+                            @ResponseHeader(
+                                    name = "Last-Modified",
+                                    description = "Date and time the resource was last modified.\n" +
+                                            "Used by caches, or in conditional requests."),
+                    }),
+            @ApiResponse(
+                    code = 400,
+                    message = "Bad Request. \n Invalid Device Identifiers found.",
+                    response = Response.class),
+            @ApiResponse(
+                    code = 401,
+                    message = "Unauthorized. \n Unauthorized request."),
+            @ApiResponse(
+                    code = 500,
+                    message = "Internal Server Error. \n Error occurred while executing command operation to"
+                            + " send keywords",
+                    response = Response.class)
+    })
+    Response sendKeyWords(
+            @ApiParam(
+                    name = "deviceId",
+                    value = "The registered device Id.",
+                    required = true)
+            @PathParam("deviceId") String deviceId,
+            @ApiParam(
+                    name = "keywords",
+                    value = "The key words to be sent. (Comma separated values)",
+                    required = true)
+            @QueryParam("keywords") String keywords);
 
     /**
      * End point to send the key words to the device
@@ -63,34 +119,222 @@ public interface AndroidSenseService {
      * @param deviceId  The registered device Id.
      * @param threshold The key words to be sent. (Comma separated values)
      */
-    @Path("device/{deviceId}/words/threshold")
     @POST
-    @Scope(key = "device:android-sense:enroll", name = "", description = "")
+    @Path("device/{deviceId}/words/threshold")
-    Response sendThreshold(@PathParam("deviceId") String deviceId, @QueryParam("threshold") String threshold);
+    @ApiOperation(
+            httpMethod = "POST",
+            value = "End point to send threshold value to the device",
+            notes = "",
+            tags = "android_sense",
+            extensions = {
+                    @Extension(properties = {
+                            @ExtensionProperty(name = "", value = "perm:android-sense:enroll")
+                    })
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    code = 200,
+                    message = "OK.",
+                    response = Response.class,
+                    responseHeaders = {
+                            @ResponseHeader(
+                                    name = "Content-Type",
+                                    description = "The content type of the body"),
+                            @ResponseHeader(
+                                    name = "Last-Modified",
+                                    description = "Date and time the resource was last modified.\n" +
+                                            "Used by caches, or in conditional requests."),
+                    }),
+            @ApiResponse(
+                    code = 400,
+                    message = "Bad Request. \n Invalid Device Identifiers found.",
+                    response = Response.class),
+            @ApiResponse(
+                    code = 401,
+                    message = "Unauthorized. \n Unauthorized request."),
+            @ApiResponse(
+                    code = 500,
+                    message = "Internal Server Error. \n Error occurred while executing command operation to"
+                            + " send threashold",
+                    response = Response.class)
+    })
+    Response sendThreshold(
+            @ApiParam(
+                    name = "deviceId",
+                    value = "The registered device Id.",
+                    required = true)
+            @PathParam("deviceId") String deviceId,
+            @ApiParam(
+                    name = "threshold",
+                    value = "Threshold to be sent.",
+                    required = true)
+            @QueryParam("threshold") String threshold);
 
-    @Path("device/{deviceId}/words")
+    /**
+     * End point to remove key words from the device
+     */
     @DELETE
-    @Scope(key = "device:android-sense:enroll", name = "", description = "")
+    @Path("device/{deviceId}/words")
-    Response removeKeyWords(@PathParam("deviceId") String deviceId, @QueryParam("words") String words);
+    @ApiOperation(
+            httpMethod = "DELETE",
+            value = "Remove key words from the device",
+            notes = "",
+            response = Response.class,
+            tags = "android_sense",
+            extensions = {
+                    @Extension(properties = {
+                            @ExtensionProperty(name = "", value = "perm:android-sense:enroll")
+                    })
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    code = 200,
+                    message = "OK.",
+                    response = Response.class,
+                    responseHeaders = {
+                            @ResponseHeader(
+                                    name = "Content-Type",
+                                    description = "The content type of the body"),
+                            @ResponseHeader(
+                                    name = "Last-Modified",
+                                    description = "Date and time the resource was last modified.\n" +
+                                            "Used by caches, or in conditional requests."),
+                    }),
+            @ApiResponse(
+                    code = 400,
+                    message = "Bad Request. \n Invalid Device Identifiers found.",
+                    response = Response.class),
+            @ApiResponse(
+                    code = 401,
+                    message = "Unauthorized. \n Unauthorized request."),
+            @ApiResponse(
+                    code = 500,
+                    message = "Internal Server Error. \n Error occurred while executing command operation to"
+                            + " send threashold",
+                    response = Response.class)
+    })
+    Response removeKeyWords(
+            @ApiParam(
+                    name = "deviceId",
+                    value = "The registered device Id.",
+                    required = true)
+            @PathParam("deviceId") String deviceId,
+            @ApiParam(
+                    name = "words",
+                    value = "The key words to be sent. (Comma separated values)",
+                    required = true)
+            @QueryParam("words") String words);
 
     /**
      * Retrieve Sensor data for the device type
      */
-    @Path("stats/{deviceId}/sensors/{sensorName}")
     @GET
-    @Consumes("application/json")
+    @Path("stats/{deviceId}/sensors/{sensorName}")
-    @Scope(key = "device:android-sense:enroll", name = "", description = "")
+    @ApiOperation(
-    @Produces("application/json")
+            consumes = "application/json",
-    Response getAndroidSenseDeviceStats(@PathParam("deviceId") String deviceId, @PathParam("sensorName") String sensor,
+            produces = "application/json",
-                                        @QueryParam("from") long from, @QueryParam("to") long to);
+            httpMethod = "GET",
+            value = "Retrieve Sensor data for the device type",
+            notes = "",
+            response = Response.class,
+            tags = "android_sense",
+            extensions = {
+                    @Extension(properties = {
+                            @ExtensionProperty(name = "", value = "perm:android-sense:enroll")
+                    })
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    code = 200,
+                    message = "OK.",
+                    response = Response.class,
+                    responseHeaders = {
+                            @ResponseHeader(
+                                    name = "Content-Type",
+                                    description = "The content type of the body"),
+                            @ResponseHeader(
+                                    name = "Last-Modified",
+                                    description = "Date and time the resource was last modified.\n" +
+                                            "Used by caches, or in conditional requests."),
+                    }),
+            @ApiResponse(
+                    code = 400,
+                    message = "Bad Request. \n Invalid Device Identifiers found.",
+                    response = Response.class),
+            @ApiResponse(
+                    code = 401,
+                    message = "Unauthorized. \n Unauthorized request."),
+            @ApiResponse(
+                    code = 500,
+                    message = "Internal Server Error. \n Error on retrieving stats",
+                    response = Response.class)
+    })
+    Response getAndroidSenseDeviceStats(
+            @ApiParam(
+                    name = "deviceId",
+                    value = "The registered device Id.",
+                    required = true)
+            @PathParam("deviceId") String deviceId,
+            @ApiParam(
+                    name = "sensorName",
+                    value = "Name of the sensor",
+                    required = true)
+            @PathParam("sensorName") String sensor,
+            @ApiParam(
+                    name = "from",
+                    value = "Get stats from what time",
+                    required = true)
+            @QueryParam("from") long from,
+            @ApiParam(
+                    name = "to",
+                    value = "Get stats up to what time",
+                    required = true)
+            @QueryParam("to") long to);
 
     /**
      * Enroll devices.
      */
-    @Path("device/{device_id}/register")
     @POST
-    @Scope(key = "device:android-sense:enroll", name = "", description = "")
+    @Path("device/{device_id}/register")
-    Response register(@PathParam("device_id") String deviceId, @QueryParam("deviceName") String deviceName);
+    @ApiOperation(
+            httpMethod = "POST",
+            value = "Enroll device",
+            notes = "",
+            response = Response.class,
+            tags = "android_sense",
+            extensions = {
+                    @Extension(properties = {
+                            @ExtensionProperty(name = "", value = "perm:android-sense:enroll")
+                    })
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    code = 202,
+                    message = "Accepted.",
+                    response = Response.class),
+            @ApiResponse(
+                    code = 406,
+                    message = "Not Acceptable"),
+            @ApiResponse(
+                    code = 500,
+                    message = "Internal Server Error. \n Error on retrieving stats",
+                    response = Response.class)
+    })
+    Response register(
+            @ApiParam(
+                    name = "deviceId",
+                    value = "Device identifier id of the device to be added",
+                    required = true)
+            @PathParam("device_id") String deviceId,
+            @ApiParam(
+                    name = "deviceName",
+                    value = "Device name of the device to be added",
+                    required = true)
+            @QueryParam("deviceName") String deviceName);
 
 }