diff --git a/hadoop-hdfs-project/hadoop-hdfs/pom.xml b/hadoop-hdfs-project/hadoop-hdfs/pom.xml index bc72bd2dba..e45a6e91ab 100644 --- 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"> rocksdbjni 5.5.5 + + io.swagger + swagger-annotations + 1.5.9 + provided + org.bouncycastle @@ -441,6 +447,48 @@ http://maven.apache.org/xsd/maven-4.0.0.xsd"> + + com.github.kongchen + swagger-maven-plugin + 3.1.5 + + + compile + + generate + + + + + + + false + target/webapps/static + ozone.swagger + + http + + localhost:9864 + / + + org.apache.hadoop.ozone.web.interfaces + + + HDFS Ozone REST Api + ${project.version} + + Apache Hadoop project + https://hadoop.apache.org + + + http://www.apache.org/licenses/LICENSE-2.0.html + Apache 2.0 + + + + + + diff --git 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 index a123d694e1..ad013fd534 100644 --- 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 @@ * 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 @@ Response createBucket(@PathParam("volume") String volume, * @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 @@ Response updateBucket(@PathParam("volume") String volume, * @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 @@ Response deleteBucket(@PathParam("volume") String volume, @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) diff --git 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 index ef70a6bcea..b4738ced19 100644 --- 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 @@ /** * 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 @@ Response putKey(@PathParam("volume") String volume, * @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 @@ Response getKey(@PathParam("volume") String volume, * @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) diff --git 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 index 1d0b1af967..8977c9feaa 100644 --- 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 @@ */ @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 @@ Response createVolume(@PathParam("volume") String 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 @@ Response updateVolume(@PathParam("volume") String 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 @@ Response deleteVolume(@PathParam("volume") String 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,