Merge pull request #507 from madhawap/release-3.0.x

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

@@ -23,9 +23,25 @@ import io.swagger.annotations.*;
 import org.wso2.carbon.apimgt.annotations.api.Scope;
 import org.wso2.carbon.apimgt.annotations.api.Scopes;
 import org.wso2.carbon.device.mgt.iot.androidsense.service.impl.constants.AndroidSenseConstants;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+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 javax.ws.rs.*;
 import javax.ws.rs.core.MediaType;
+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(
@@ -61,14 +77,12 @@ 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
+    @Path("device/{deviceId}/words")
     @ApiOperation(
-            consumes = MediaType.APPLICATION_JSON,
             httpMethod = "POST",
-            value = "Send the key words to the device",
+            value = "End point to send the key words to the device",
             notes = "",
-            response = Response.class,
             tags = "android_sense",
             extensions = {
                     @Extension(properties = {
@@ -76,7 +90,44 @@ public interface AndroidSenseService {
                     })
             }
     )
-    Response sendKeyWords(@PathParam("deviceId") String deviceId, @QueryParam("keywords") String keywords);
+    @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
@@ -84,14 +135,12 @@ 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
+    @Path("device/{deviceId}/words/threshold")
     @ApiOperation(
-            consumes = MediaType.APPLICATION_JSON,
             httpMethod = "POST",
-            value = "Send threshold value to the device",
+            value = "End point to send threshold value to the device",
             notes = "",
-            response = Response.class,
             tags = "android_sense",
             extensions = {
                     @Extension(properties = {
@@ -99,12 +148,51 @@ public interface AndroidSenseService {
                     })
             }
     )
-    Response sendThreshold(@PathParam("deviceId") String deviceId, @QueryParam("threshold") String threshold);
+    @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
+    @Path("device/{deviceId}/words")
     @ApiOperation(
-            consumes = MediaType.APPLICATION_JSON,
             httpMethod = "DELETE",
             value = "Remove key words from the device",
             notes = "",
@@ -116,17 +204,53 @@ public interface AndroidSenseService {
                     })
             }
     )
-    Response removeKeyWords(@PathParam("deviceId") String deviceId, @QueryParam("words") String words);
+    @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}")
-    @Produces("application/json")
     @ApiOperation(
-            consumes = MediaType.APPLICATION_JSON,
+            consumes = "application/json",
+            produces = "application/json",
             httpMethod = "GET",
             value = "Retrieve Sensor data for the device type",
             notes = "",
@@ -138,16 +262,60 @@ public interface AndroidSenseService {
                     })
             }
     )
-    Response getAndroidSenseDeviceStats(@PathParam("deviceId") String deviceId, @PathParam("sensorName") String sensor,
+    @ApiResponses(value = {
-                                        @QueryParam("from") long from, @QueryParam("to") long to);
+            @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
+    @Path("device/{device_id}/register")
     @ApiOperation(
-            consumes = MediaType.APPLICATION_JSON,
             httpMethod = "POST",
             value = "Enroll device",
             notes = "",
@@ -159,7 +327,30 @@ public interface AndroidSenseService {
                     })
             }
     )
-    Response register(@PathParam("device_id") String deviceId, @QueryParam("deviceName") String deviceName);
+    @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);
 
 }