Add Swagger comments and dependencies to appsm with REST APIs

ONOS-2704 and ONOS-2705

Change-Id: I77655af94f8b5aba647a94b3b786a6de8a285d7c

@@ -42,6 +42,11 @@ public class FabricWebResource extends AbstractWebResource {
 
     private static final FabricVlanCodec VLAN_CODEC = new FabricVlanCodec();
 
+    /**
+     * Get all CORD fabric VLANs.
+     *
+     * @return array of cord VLANs in the system.
+     */
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     public Response getVlans() {
@@ -53,6 +58,14 @@ public class FabricWebResource extends AbstractWebResource {
         return ok(result.toString()).build();
     }
 
+    /**
+     * Create a CORD fabric VLAN.
+     *
+     * @param input JSON stream describing new VLAN
+     * @return status of the request - CREATED if the JSON is correct,
+     * INTERNAL_SERVER_ERROR if the JSON is invalid
+     * @throws IOException if the JSON is invalid
+     */
     @POST
     @Path("add")
     @Consumes(MediaType.APPLICATION_JSON)
@@ -66,9 +79,15 @@ public class FabricWebResource extends AbstractWebResource {
         return Response.ok().build();
     }
 
+    /**
+     * Delete a CORD fabric VLAN.
+     *
+     * @param vlan identifier of the VLAN to remove
+     * @return status of the request - OK
+     */
     @DELETE
     @Path("{vlan}")
-    public Response deleteVlan(@PathParam("vlan") String vlan) throws IOException {
+    public Response deleteVlan(@PathParam("vlan") String vlan) {
         VlanId vlanId = VlanId.vlanId(Short.parseShort(vlan));
 
         FabricService fabricService = get(FabricService.class);

@@ -34,11 +34,20 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.List;
 
+/**
+ * Query, create and remove segment routing plicies.
+ */
 @Path("policy")
 public class PolicyWebResource extends AbstractWebResource {
 
     private static final PolicyCodec POLICY_CODEC = new PolicyCodec();
 
+    /**
+     * Get all segment routing policies.
+     * Returns an array of segment routing policies.
+     *
+     * @return status of OK
+     */
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     public Response getPolicy() {
@@ -50,6 +59,14 @@ public class PolicyWebResource extends AbstractWebResource {
         return ok(result.toString()).build();
     }
 
+    /**
+     * Create a new segment routing policy.
+     *
+     * @param input JSON stream for policy to create
+     * @return status of the request - OK if the policy is created,
+     * INTERNAL_SERVER_ERROR if the JSON is invalid or the policy cannot be created
+     * @throws IOException
+     */
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
     public Response createPolicy(InputStream input) throws IOException {
@@ -66,6 +83,14 @@ public class PolicyWebResource extends AbstractWebResource {
         }
     }
 
+    /**
+     * Delete a segment routing policy.
+     *
+     * @param input JSON stream for policy to delete
+     * @return status of the request - OK if the policy is removed,
+     * INTERNAL_SERVER_ERROR otherwise
+     * @throws IOException if JSON is invalid
+     */
     @DELETE
     @Consumes(MediaType.APPLICATION_JSON)
     public Response removePolicy(InputStream input) throws IOException {

@@ -34,11 +34,20 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.List;
 
+/**
+ * Query, create and remove segment routing tunnels.
+ */
 @Path("tunnel")
 public class TunnelWebResource extends AbstractWebResource {
 
     private static final TunnelCodec TUNNEL_CODEC = new TunnelCodec();
 
+    /**
+     * Get all segment routing tunnels.
+     * Returns an array of segment routing tunnels.
+     *
+     * @return status of OK
+     */
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     public Response getTunnel() {
@@ -50,6 +59,14 @@ public class TunnelWebResource extends AbstractWebResource {
         return ok(result.toString()).build();
     }
 
+    /**
+     * Create a new segment routing tunnel.
+     *
+     * @param input JSON stream for tunnel to create
+     * @return status of the request - OK if the tunnel is created,
+     * INTERNAL_SERVER_ERROR if the JSON is invalid or the tunnel cannot be created
+     * @throws IOException if the JSON is invalid
+     */
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
     public Response createTunnel(InputStream input) throws IOException {
@@ -62,6 +79,14 @@ public class TunnelWebResource extends AbstractWebResource {
         return Response.ok().build();
     }
 
+    /**
+     * Delete a segment routing tunnel.
+     *
+     * @param input JSON stream for tunnel to delete
+     * @return status of the request - OK if the tunnel is removed,
+     * INTERNAL_SERVER_ERROR otherwise
+     * @throws IOException if JSON is invalid
+     */
     @DELETE
     @Consumes(MediaType.APPLICATION_JSON)
     public Response removeTunnel(InputStream input) throws IOException {

@@ -34,6 +34,11 @@
     <properties>
         <onos.app.name>org.onosproject.demo</onos.app.name>
         <web.context>/onos/demo</web.context>
+        <api.title>ONOS Flow Throughput Test App API</api.title>
+        <api.description>
+            APIs for interacting with the flow throughput test application.
+        </api.description>
+        <api.package>org.onosproject.demo</api.package>
     </properties>
 
     <dependencies>
@@ -82,6 +87,10 @@
                 <configuration>
                     <instructions>
                         <_wab>src/main/webapp/</_wab>
+                        <Include-Resource>
+                            WEB-INF/classes/apidoc/swagger.json=target/swagger.json,
+                            {maven-resources}
+                        </Include-Resource>
                         <Bundle-SymbolicName>
                             ${project.groupId}.${project.artifactId}
                         </Bundle-SymbolicName>

@@ -37,7 +37,13 @@ import java.util.Optional;
 public class DemoResource extends BaseResource {
 
 
-
+    /**
+     * Start the flow test.
+     *
+     * @param input JSON describing how to run the flow test
+     * @return response code OK
+     * @throws IOException if the JSON processing fails
+     */
     @POST
     @Path("flowTest")
     @Consumes(MediaType.APPLICATION_JSON)
@@ -49,6 +55,13 @@ public class DemoResource extends BaseResource {
         return Response.ok(demo.flowTest(Optional.ofNullable(cfg)).toString()).build();
     }
 
+    /**
+     * Set up the flow test.
+     *
+     * @param input JSON describing how to configure the flow test
+     * @return response code OK
+     * @throws IOException if the JSON processing fails
+     */
     @POST
     @Path("setup")
     @Consumes(MediaType.APPLICATION_JSON)
@@ -70,10 +83,15 @@ public class DemoResource extends BaseResource {
         return Response.ok(mapper.createObjectNode().toString()).build();
     }
 
+    /**
+     * Tear down the flow test.
+     *
+     * @return response code OK
+     */
     @GET
     @Path("teardown")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response tearDown() throws IOException {
+    public Response tearDown() {
         ObjectMapper mapper = new ObjectMapper();
         DemoAPI demo = get(DemoAPI.class);
         demo.tearDown();

@@ -34,6 +34,12 @@
     <properties>
         <onos.app.name>org.onosproject.virtualbng</onos.app.name>
         <web.context>/onos/virtualbng</web.context>
+        <api.version>1.0.0</api.version>
+        <api.title>ONOS Virtual BNG Gateway REST API</api.title>
+        <api.description>
+            APIs for interacting with the Virtual Broadband Network Gateway (BNG) application.
+        </api.description>
+        <api.package>org.onosproject.virtualbng</api.package>
     </properties>
 
     <dependencies>
@@ -72,6 +78,10 @@
                 <configuration>
                     <instructions>
                         <_wab>src/main/webapp/</_wab>
+                        <Include-Resource>
+                            WEB-INF/classes/apidoc/swagger.json=target/swagger.json,
+                            {maven-resources}
+                        </Include-Resource>
                         <Bundle-SymbolicName>
                             ${project.groupId}.${project.artifactId}
                         </Bundle-SymbolicName>
@@ -98,4 +108,4 @@
         </plugins>
     </build>
 
-</project>
\ No newline at end of file
+</project>

@@ -37,13 +37,21 @@ import org.onosproject.rest.AbstractWebResource;
 import org.slf4j.Logger;
 
 /**
- * This class provides REST services to virtual BNG.
+ * REST services to interact with the virtual BNG.
  */
 @Path("privateip")
 public class VbngResource extends AbstractWebResource {
 
     private final Logger log = getLogger(getClass());
 
+    /**
+     * Create a new virtual BNG connection.
+     *
+     * @param privateIp IP Address for the BNG private network
+     * @param mac MAC address for the host
+     * @param hostName name of the host
+     * @return public IP address for the new connection
+     */
     @POST
     @Path("{privateip}/{mac}/{hostname}")
     public String privateIpAddNotification(@PathParam("privateip")
@@ -77,6 +85,12 @@ public class VbngResource extends AbstractWebResource {
         }
     }
 
+    /**
+     * Delete a virtual BNG connection.
+     *
+     * @param privateIp IP Address for the BNG private network
+     * @return public IP address for the new connection
+     */
     @DELETE
     @Path("{privateip}")
     public String privateIpDeleteNotification(@PathParam("privateip")
@@ -101,6 +115,11 @@ public class VbngResource extends AbstractWebResource {
         }
     }
 
+    /**
+     * Query virtual BNG map.
+     *
+     * @return IP Address map
+     */
     @GET
     @Path("map")
     @Produces(MediaType.APPLICATION_JSON)
@@ -119,4 +138,4 @@ public class VbngResource extends AbstractWebResource {
 
         return ok(result.toString()).build();
     }
-}
\ No newline at end of file
+}