HDFS-12558. Ozone: Clarify the meaning of rpc.metrics.percentiles.intervals on KSM/SCM web ui. Contributed by Elek, Marton.

hadoop-hdfs-project/hadoop-hdfs/pom.xml

@@ -193,6 +193,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>
@@ -455,6 +461,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>
 

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)

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)

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,