HDFS-12690. Ozone: generate swagger descriptor for the Ozone REST Api. Contributed by Elek, Marton.

2017-10-26 11:28:08 -07:00 · 2017-10-26 11:28:08 -07:00 · 333dae888c
parent 0582d8b1b1
commit 333dae888c
4 changed files with 176 additions and 1 deletions
--- a/hadoop-hdfs-project/hadoop-hdfs/pom.xml
+++ b/hadoop-hdfs-project/hadoop-hdfs/pom.xml
@ -192,6 +192,12 @@ http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <artifactId>rocksdbjni</artifactId>
      <version>5.5.5</version>
    </dependency>
+    <dependency>
+      <groupId>io.swagger</groupId>
+      <artifactId>swagger-annotations</artifactId>
+      <version>1.5.9</version>
+      <scope>provided</scope>
+    </dependency>
    <!-- 'mvn dependency:analyze' fails to detect use of this dependency -->
    <dependency>
      <groupId>org.bouncycastle</groupId>
@ -441,6 +447,48 @@ http://maven.apache.org/xsd/maven-4.0.0.xsd">
          </filesets>
        </configuration>
      </plugin>
+      <plugin>
+        <groupId>com.github.kongchen</groupId>
+        <artifactId>swagger-maven-plugin</artifactId>
+        <version>3.1.5</version>
+        <executions>
+          <execution>
+            <phase>compile</phase>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <apiSources>
+            <apiSource>
+              <springmvc>false</springmvc>
+              <swaggerDirectory>target/webapps/static</swaggerDirectory>
+              <swaggerFileName>ozone.swagger</swaggerFileName>
+              <schemes>
+                <scheme>http</scheme>
+              </schemes>
+              <host>localhost:9864</host>
+              <basePath>/</basePath>
+              <locations>
+                <location>org.apache.hadoop.ozone.web.interfaces</location>
+              </locations>
+              <info>
+                <title>HDFS Ozone REST Api</title>
+                <version>${project.version}</version>
+                <contact>
+                  <name>Apache Hadoop project</name>
+                  <url>https://hadoop.apache.org</url>
+                </contact>
+                <license>
+                  <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
+                  <name>Apache 2.0</name>
+                </license>
+              </info>
+            </apiSource>
+          </apiSources>
+        </configuration>
+      </plugin>
    </plugins>
  </build>

--- a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Bucket.java
+++ b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Bucket.java
@ -18,6 +18,10 @@

 package org.apache.hadoop.ozone.web.interfaces;

+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
 import org.apache.hadoop.ozone.web.exceptions.OzoneException;
 import org.apache.hadoop.ozone.client.rest.headers.Header;

@ -42,6 +46,7 @@ import javax.ws.rs.core.UriInfo;
 * bucket related functionality.
 */
@Path("/{volume}/{bucket}")
+@Api(tags = "bucket")
 public interface Bucket {
  /**
   * createBucket call handles the POST request for Creating a Bucket.
@ -57,6 +62,16 @@ public interface Bucket {
   * @throws OzoneException
   */
  @POST
+  @ApiOperation("Create new bucket to a volume")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response createBucket(@PathParam("volume") String volume,
                        @PathParam("bucket") String bucket,
                        @Context Request req, @Context UriInfo info,
@ -76,6 +91,16 @@ public interface Bucket {
   * @throws OzoneException
   */
  @PUT
+  @ApiOperation("Update bucket")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response updateBucket(@PathParam("volume") String volume,
                        @PathParam("bucket") String bucket,
                        @Context Request req, @Context UriInfo info,
@ -95,6 +120,16 @@ public interface Bucket {
   * @throws OzoneException
   */
  @DELETE
+  @ApiOperation("Deletes an empty bucket.")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response deleteBucket(@PathParam("volume") String volume,
                        @PathParam("bucket") String bucket,
                        @Context Request req, @Context UriInfo info,
@ -119,6 +154,16 @@ public interface Bucket {

  @GET
  @Produces(MediaType.APPLICATION_JSON)
+  @ApiOperation("List contents of a bucket")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response listBucket(@PathParam("volume") String volume,
                      @PathParam("bucket") String bucket,
                      @DefaultValue(Header.OZONE_LIST_QUERY_KEY)
--- a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Keys.java
+++ b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Keys.java
@ -18,6 +18,10 @@

 package org.apache.hadoop.ozone.web.interfaces;

+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
 import org.apache.hadoop.ozone.web.exceptions.OzoneException;
 import org.apache.hadoop.ozone.client.rest.headers.Header;

@ -39,8 +43,8 @@ import java.io.InputStream;
 /**
 * This interface defines operations permitted on a key.
 */
-
@Path("/{volume}/{bucket}/{keys:.*}")
+@Api(tags = "key")
 public interface Keys {

  /**
@ -61,6 +65,18 @@ public interface Keys {
   */
  @PUT
  @Consumes(MediaType.WILDCARD)
+  @ApiOperation(value = "Adds a key to an existing bucket.",notes = "If the "
+      + "object already exists this call will overwrite or add with new version "
+      + "number if the bucket versioning is turned on.")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response putKey(@PathParam("volume") String volume,
      @PathParam("bucket") String bucket, @PathParam("keys") String keys,
      InputStream is, @Context Request req, @Context UriInfo info,
@ -82,6 +98,16 @@ public interface Keys {
   * @throws OzoneException
   */
  @GET
+  @ApiOperation("Gets the Key if it exists.")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response getKey(@PathParam("volume") String volume,
      @PathParam("bucket") String bucket, @PathParam("keys") String keys,
      @QueryParam(Header.OZONE_LIST_QUERY_TAG) String info,
@ -102,6 +128,16 @@ public interface Keys {
   * @throws OzoneException
   */
  @DELETE
+  @ApiOperation("Deletes an existing key")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response deleteKey(@PathParam("volume") String volume,
      @PathParam("bucket") String bucket, @PathParam("keys") String keys,
      @Context Request req, @Context UriInfo info, @Context HttpHeaders headers)
--- a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Volume.java
+++ b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/ozone/web/interfaces/Volume.java
@ -18,6 +18,10 @@

 package org.apache.hadoop.ozone.web.interfaces;

+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
 import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.ozone.web.exceptions.OzoneException;
 import org.apache.hadoop.ozone.client.rest.headers.Header;
@ -42,6 +46,7 @@ import javax.ws.rs.core.UriInfo;
 */
@InterfaceAudience.Private
@Path("/{volume}")
+@Api(tags = "volume")
 public interface Volume {

  /**
@ -64,6 +69,16 @@ public interface Volume {
   */

  @POST
+  @ApiOperation("Creates a Volume owned by the user")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response createVolume(@PathParam("volume") String volume,
      @DefaultValue(Header.OZONE_QUOTA_UNDEFINED)
      @QueryParam(Header.OZONE_QUOTA_QUERY_TAG) String quota,
@ -89,6 +104,16 @@ public interface Volume {
   * @throws OzoneException
   */
  @PUT
+  @ApiOperation("Updates a Volume owned by the user")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response updateVolume(@PathParam("volume") String volume,
      @DefaultValue(Header.OZONE_QUOTA_UNDEFINED)
      @QueryParam(Header.OZONE_QUOTA_QUERY_TAG) String quota,
@ -105,6 +130,16 @@ public interface Volume {
   * @throws OzoneException
   */
  @DELETE
+  @ApiOperation("Deletes a Volume if it is empty")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response deleteVolume(@PathParam("volume") String volume,
      @Context Request req, @Context UriInfo uriInfo,
      @Context HttpHeaders headers) throws OzoneException;
@ -122,6 +157,17 @@ public interface Volume {
   * @throws OzoneException
   */
  @GET
+  @ApiOperation(value = "Returns Volume info", notes = "This API can be "
+      + "invoked either by admin or the owner")
+  @ApiImplicitParams({
+      @ApiImplicitParam(name = "x-ozone-version", example = "v1", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "x-ozone-user", example = "user", required =
+          true, paramType = "header"),
+      @ApiImplicitParam(name = "Date", example = "Date: Mon, 26 Jun 2017 "
+          + "04:23:30 GMT", required = true, paramType = "header"),
+      @ApiImplicitParam(name = "Authorization", example = "OZONE", required =
+          true, paramType = "header")})
  Response getVolumeInfo(@PathParam("volume") String volume,
      @DefaultValue(Header.OZONE_LIST_QUERY_BUCKET)
      @QueryParam(Header.OZONE_LIST_QUERY_TAG) String info,