ATLAS-1370: Atlas REST API document generation with enunciate

Signed-off-by: Madhan Neethiraj <madhan@apache.org>

build-tools/src/main/resources/enunciate.xml

@@ -17,39 +17,27 @@
   -->
 
 <enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-           xsi:noNamespaceSchemaLocation="http://enunciate.codehaus.org/schemas/enunciate-1.29.xsd">
-    <api-import pattern="org.apache.atlas.web.resources.*"/>
-    <services>
-        <rest defaultRestSubcontext="/api/atlas/">
-            <custom-resource-parameter-annotation
-                    qualifiedName="org.glassfish.jersey.media.multipart.FormDataParam"/>
-        </rest>
-    </services>
-    <webapp disabled="true"/>
+           xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.8.0.xsd">
+    <title>Atlas REST API</title>
+    <description> Atlas exposes a variety of REST endpoints to work with types, entities, lineage and data discovery.</description>
+    <api-classes>
+        <include pattern="org.apache.atlas.web.rest.*"/>
+        <include pattern="org.apache.atlas.model.*"/>
+    </api-classes>
+
     <modules>
-        <disable-rule id="csharp.warnings"/>
-        <disable-rule id="c.warnings"/>
-        <disable-rule id="obj-c.warnings"/>
-        <docs docsDir="apidocs" title="Apache Data Governance APIs"
-              includeDefaultDownloads="true" includeExampleXml="false"
-              disableRestMountpoint="true" forceExampleJson="true">
-        </docs>
-        <basic-app disabled="true"/>
-        <c disabled="true"/>
-        <csharp disabled="true"/>
-        <jaxws-ri disabled="true"/>
-        <jersey disabled="true"/>
-        <obj-c disabled="true"/>
-        <amf disabled="true"/>
-        <gwt disabled="true"/>
-        <jboss disabled="true"/>
-        <object-c disabled="true"/>
-        <rubby disabled="true"/>
-        <java-client disabled="true"/>
-        <jaxws-client disabled="true"/>
-        <xml forceExampleJson="true"/>
-        <jaxws-support disabled="false"/>
-        <cxf disabled="false" enableJaxrs="true" enableJaxws="true"/>
-        <jaxws disabled="false"/>
+        <swagger/>
+        <jackson/>
+        <jackson1 disabled="true"/>
+        <c-xml-client disabled="true"/>
+        <java-json-client disabled="true"/>
+        <csharp-xml-client disabled="true"/>
+        <java-xml-client disabled="true"/>
+        <javascript-client disabled="true"/>
+        <ruby-json-client disabled="true"/>
+        <gwt-json-overlay disabled="true"/>
+        <php-xml-client disabled="true"/>
+        <php-json-client disabled="true"/>
+        <jaxws disabled="true"/>
     </modules>
 </enunciate>

docs/src/site/twiki/index.twiki

@@ -55,7 +55,8 @@ allows integration with the whole enterprise data ecosystem.
 
 ---++ API Documentation
 
-   * <a href="api/rest.html">REST API Documentation</a>
+   * <a href="api/v2/index.html">REST API Documentation</a>
+   * <a href="api/rest.html">Legacy API Documentation</a>
 
 ---++ Developer Setup Documentation
    * [[EclipseSetup][Developer Setup: Eclipse]]

intg/src/main/java/org/apache/atlas/AtlasErrorCode.java

@@ -65,15 +65,14 @@ public enum AtlasErrorCode {
     UNKNOWN_ATTRIBUTE(400, "ATLAS40034E", "Attribute {0} not found for type {1}"),
     SYSTEM_TYPE(400, "ATLAS40035E", "{0} is a System-type"),
     INVALID_STRUCT_VALUE(400, "ATLAS40036E", "not a valid struct value {0}"),
+    INSTANCE_LINEAGE_INVALID_PARAMS(400, "ATLAS40037E", "Invalid lineage query parameters passed {0}: {1}"),
 
     // All Not found enums go here
     TYPE_NAME_NOT_FOUND(404, "ATLAS4041E", "Given typename {0} was invalid"),
     TYPE_GUID_NOT_FOUND(404, "ATLAS4042E", "Given type guid {0} was invalid"),
     EMPTY_RESULTS(404, "ATLAS4044E", "No result found for {0}"),
     INSTANCE_GUID_NOT_FOUND(404, "ATLAS4045E", "Given instance guid {0} is invalid/not found"),
-    INSTANCE_LINEAGE_INVALID_PARAMS(404, "ATLAS4046E", "Invalid lineage query parameters passed {0}: {1}"),
     INSTANCE_LINEAGE_QUERY_FAILED(404, "ATLAS4047E", "Instance lineage query failed {0}"),
-    DISCOVERY_QUERY_FAILED(404, "ATLAS4048E", "Discovery query failed {0}"),
     INSTANCE_CRUD_INVALID_PARAMS(404, "ATLAS4049E", "Invalid instance creation/updation parameters passed : {0}"),
 
     INSTANCE_BY_UNIQUE_ATTRIBUTE_NOT_FOUND(404, "ATLAS40410E", "Instance {0} with unique attribute {1} does not exist"),
@@ -87,9 +86,10 @@ public enum AtlasErrorCode {
     INTERNAL_ERROR(500, "ATLAS5001E", "Internal server error {0}"),
     INDEX_CREATION_FAILED(500, "ATLAS5002E", "Index creation failed for {0}"),
     INDEX_ROLLBACK_FAILED(500, "ATLAS5003E", "Index rollback failed for {0}"),
-    FAILED_TO_OBTAIN_TYPE_UPDATE_LOCK(500, "ATLAS5004E", "Failed to get the lock; another type update might be in progress. Please try again"),
-    FAILED_TO_OBTAIN_IMPORT_EXPORT_LOCK(500, "ATLAS5005E", "Another import or export is in progress. Please try again"),
-    NOTIFICATION_FAILED(500, "ATLAS5005E", "Failed to notify for change {0}");
+    DISCOVERY_QUERY_FAILED(500, "ATLAS5004E", "Discovery query failed {0}"),
+    FAILED_TO_OBTAIN_TYPE_UPDATE_LOCK(500, "ATLAS5005E", "Failed to get the lock; another type update might be in progress. Please try again"),
+    FAILED_TO_OBTAIN_IMPORT_EXPORT_LOCK(500, "ATLAS5006E", "Another import or export is in progress. Please try again"),
+    NOTIFICATION_FAILED(500, "ATLAS5007E", "Failed to notify for change {0}");
 
     private String errorCode;
     private String errorMessage;

pom.xml

@@ -483,6 +483,7 @@
         <skipITs>false</skipITs>
         <skipDocs>true</skipDocs>
         <skipSite>true</skipSite>
+        <skipEnunciate>true</skipEnunciate>
         <projectBaseDir>${project.basedir}</projectBaseDir>
         <jetty-maven-plugin.stopWait>10</jetty-maven-plugin.stopWait>
 
@@ -523,22 +524,6 @@
             </properties>
         </profile>
 
-        <profile>
-            <id>jdk7</id>
-            <activation>
-                <jdk>[1.7,1.8)</jdk>
-            </activation>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.codehaus.enunciate</groupId>
-                        <artifactId>maven-enunciate-plugin</artifactId>
-                        <version>1.29</version>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-
         <profile>
             <id>dist</id>
             <activation>
@@ -1433,6 +1418,14 @@
                 <version>${fastutil.version}</version>
             </dependency>
 
+            <!-- API documentation  -->
+            <dependency>
+                <groupId>com.webcohesion.enunciate</groupId>
+                <artifactId>enunciate-core-annotations</artifactId>
+                <version>2.8.0</version>
+            </dependency>
+
+
             <!-- supports simple auth handler -->
             <dependency>
                 <groupId>org.apache.httpcomponents</groupId>
@@ -1682,6 +1675,20 @@
                     <artifactId>aspectj-maven-plugin</artifactId>
                     <version>1.8</version>
                 </plugin>
+
+                <plugin>
+                    <groupId>com.webcohesion.enunciate</groupId>
+                    <artifactId>enunciate-maven-plugin</artifactId>
+                    <version>2.8.0</version>
+                    <executions>
+                        <execution>
+                            <goals>
+                                <goal>docs</goal>
+                            </goals>
+                            <phase>package</phase>
+                        </execution>
+                    </executions>
+                </plugin>
             </plugins>
         </pluginManagement>
 

webapp/pom.xml

@@ -39,33 +39,6 @@
     </properties>
 
     <profiles>
-        <profile>
-            <id>jdk7</id>
-            <activation>
-                <jdk>[1.7,1.8)</jdk>
-            </activation>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.codehaus.enunciate</groupId>
-                        <artifactId>maven-enunciate-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <goals>
-                                    <goal>docs</goal>
-                                </goals>
-                                <phase>site</phase>
-                            </execution>
-                        </executions>
-                        <configuration>
-                            <!-- the directory where to put the docs -->
-                            <docsDir>${project.build.directory}/apidocs</docsDir>
-                            <configFile>${basedir}/../src/build/enunciate.xml</configFile>
-                        </configuration>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
         <profile>
             <!-- default profile is for external HBase and Solr - hence not packaging those jars -->
             <id>dist</id>
@@ -399,6 +372,12 @@
             <groupId>org.apache.atlas</groupId>
             <artifactId>atlas-server-api</artifactId>
         </dependency>
+
+        <dependency>
+            <groupId>com.webcohesion.enunciate</groupId>
+            <artifactId>enunciate-core-annotations</artifactId>
+        </dependency>
+
     </dependencies>
 
     <build>
@@ -663,6 +642,18 @@
                     </dependency>
                 </dependencies>
             </plugin>
+            <plugin>
+                <groupId>com.webcohesion.enunciate</groupId>
+                <artifactId>enunciate-maven-plugin</artifactId>
+                <configuration>
+                    <configFile>${project.parent.basedir}/build-tools/src/main/resources/enunciate.xml</configFile>
+                    <enunciateArtifactId/>
+                    <docsDir>${project.build.directory}/api/v2/</docsDir>
+                    <source>1.7</source>
+                    <target>1.7</target>
+                    <skipEnunciate>${skipEnunciate}</skipEnunciate>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 </project>

webapp/src/main/java/org/apache/atlas/web/resources/AdminResource.java

@@ -52,17 +52,26 @@ import javax.inject.Singleton;
 import javax.servlet.ServletOutputStream;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
-import javax.ws.rs.*;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.WebApplicationException;
 import javax.ws.rs.core.Context;
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
-import java.util.*;
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.concurrent.locks.ReentrantLock;
 
 import static org.apache.atlas.repository.converters.AtlasInstanceConverter.toAtlasBaseException;
 
+
 /**
  * Jersey Resource for admin operations.
  */
@@ -438,4 +447,4 @@ public class AdminResource {
 
         importExportOperationLock.lock();
     }
-}
+}

webapp/src/main/java/org/apache/atlas/web/rest/DiscoveryREST.java

@@ -30,6 +30,9 @@ import javax.ws.rs.Path;
 import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 
+/**
+ * REST interface for data discovery using dsl or full text search
+ */
 @Path("v2/search")
 @Singleton
 public class DiscoveryREST {
@@ -40,6 +43,17 @@ public class DiscoveryREST {
         this.atlasDiscoveryService = discoveryService;
     }
 
+    /**
+     * Retrieve data for the specified DSL
+     * @param query DSL query
+     * @param limit limit the result set to only include the specified number of entries
+     * @param offset start offset of the result set (useful for pagination)
+     * @return Search results
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful DSL execution with some results, might return an empty list if execution succeeded
+     * without any results
+     * @HTTP 400 Invalid DSL or query parameters
+     */
     @GET
     @Path("/dsl")
     @Consumes(Servlets.JSON_MEDIA_TYPE)
@@ -53,6 +67,17 @@ public class DiscoveryREST {
         return ret;
     }
 
+    /**
+     * Retrieve data for the specified fulltext query
+     * @param query Fulltext query
+     * @param limit limit the result set to only include the specified number of entries
+     * @param offset start offset of the result set (useful for pagination)
+     * @return Search results
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful FullText lookup with some results, might return an empty list if execution succeeded
+     * without any results
+     * @HTTP 400 Invalid fulltext or query parameters
+     */
     @GET
     @Path("/fulltext")
     @Consumes(Servlets.JSON_MEDIA_TYPE)

webapp/src/main/java/org/apache/atlas/web/rest/LineageREST.java

@@ -37,6 +37,9 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.Context;
 
+/**
+ * REST interface for an entity's lineage information
+ */
 @Path("v2/lineage")
 @Singleton
 public class LineageREST {
@@ -59,6 +62,9 @@ public class LineageREST {
      * @param depth - number of hops for lineage
      * @return AtlasLineageInfo
      * @throws AtlasBaseException
+     * @HTTP 200 If Lineage exists for the given entity
+     * @HTTP 400 Bad query parameters
+     * @HTTP 404 If no lineage is found for the given entity
      */
     @GET
     @Path("/{guid}")

webapp/src/main/java/org/apache/atlas/web/rest/TypesREST.java

@@ -18,6 +18,8 @@
 package org.apache.atlas.web.rest;
 
 import com.google.inject.Inject;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import org.apache.atlas.exception.AtlasBaseException;
 import org.apache.atlas.model.SearchFilter;
 import org.apache.atlas.model.typedef.AtlasBaseTypeDef;
@@ -46,20 +48,28 @@ import javax.ws.rs.core.Context;
 import java.util.List;
 import java.util.Set;
 
-
+/**
+ * REST interface for CRUD operations on type definitions
+ */
 @Path("v2/types")
 @Singleton
 public class TypesREST {
 
     private final AtlasTypeDefStore typeDefStore;
 
-
     @Inject
     public TypesREST(AtlasTypeDefStore typeDefStore) {
         this.typeDefStore = typeDefStore;
     }
 
-
+    /**
+     * Get type definition by it's name
+     * @param name Type name
+     * @return Type definition
+     * @throws AtlasBaseException
+     * @HTTP 200 Successful lookup by name
+     * @HTTP 404 Failed lookup by name
+     */
     @GET
     @Path("/typedef/name/{name}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -69,6 +79,13 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * @param guid GUID of the type
+     * @return Type definition
+     * @throws AtlasBaseException
+     * @HTTP 200 Successful lookup
+     * @HTTP 404 Failed lookup
+     */
     @GET
     @Path("/typedef/guid/{guid}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -82,6 +99,8 @@ public class TypesREST {
      * Bulk retrieval API for all type definitions returned as a list of minimal information header
      * @return List of AtlasTypeDefHeader {@link AtlasTypeDefHeader}
      * @throws AtlasBaseException
+     * @HTTP 200 Returns a list of {@link AtlasTypeDefHeader} matching the search criteria
+     * or an empty list if no match.
      */
     @GET
     @Path("/typedefs/headers")
@@ -98,6 +117,7 @@ public class TypesREST {
      * Bulk retrieval API for retrieving all type definitions in Atlas
      * @return A composite wrapper object with lists of all type definitions
      * @throws Exception
+     * @HTTP 200 {@link AtlasTypesDef} with type definitions matching the search criteria or else returns empty list of type definitions
      */
     @GET
     @Path("/typedefs")
@@ -110,6 +130,14 @@ public class TypesREST {
         return typesDef;
     }
 
+    /**
+     * Get the enum definition by it's name (unique)
+     * @param name enum name
+     * @return enum definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the enum definition by it's name
+     * @HTTP 404 On Failed lookup for the given name
+     */
     @GET
     @Path("/enumdef/name/{name}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -119,6 +147,14 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * Get the enum definition for the given guid
+     * @param guid enum guid
+     * @return enum definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the enum definition by it's guid
+     * @HTTP 404 On Failed lookup for the given guid
+     */
     @GET
     @Path("/enumdef/guid/{guid}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -129,6 +165,14 @@ public class TypesREST {
     }
 
 
+    /**
+     * Get the struct definition by it's name (unique)
+     * @param name struct name
+     * @return struct definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the struct definition by it's name
+     * @HTTP 404 On Failed lookup for the given name
+     */
     @GET
     @Path("/structdef/name/{name}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -138,6 +182,14 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * Get the struct definition for the given guid
+     * @param guid struct guid
+     * @return struct definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the struct definition by it's guid
+     * @HTTP 404 On Failed lookup for the given guid
+     */
     @GET
     @Path("/structdef/guid/{guid}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -147,6 +199,14 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * Get the classification definition by it's name (unique)
+     * @param name classification name
+     * @return classification definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the classification definition by it's name
+     * @HTTP 404 On Failed lookup for the given name
+     */
     @GET
     @Path("/classificationdef/name/{name}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -156,6 +216,14 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * Get the classification definition for the given guid
+     * @param guid classification guid
+     * @return classification definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the classification definition by it's guid
+     * @HTTP 404 On Failed lookup for the given guid
+     */
     @GET
     @Path("/classificationdef/guid/{guid}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -165,7 +233,14 @@ public class TypesREST {
         return ret;
     }
 
-
+    /**
+     * Get the entity definition by it's name (unique)
+     * @param name entity name
+     * @return Entity definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the entity definition by it's name
+     * @HTTP 404 On Failed lookup for the given name
+     */
     @GET
     @Path("/entitydef/name/{name}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -175,6 +250,14 @@ public class TypesREST {
         return ret;
     }
 
+    /**
+     * Get the Entity definition for the given guid
+     * @param guid entity guid
+     * @return Entity definition
+     * @throws AtlasBaseException
+     * @HTTP 200 On successful lookup of the the entity definition by it's guid
+     * @HTTP 404 On Failed lookup for the given guid
+     */
     @GET
     @Path("/entitydef/guid/{guid}")
     @Produces(Servlets.JSON_MEDIA_TYPE)
@@ -184,9 +267,7 @@ public class TypesREST {
         return ret;
     }
 
-    /******************************************************************/
-    /** Bulk API operations                                          **/
-    /******************************************************************/
+    /* Bulk API operation */
 
     /**
      * Bulk create APIs for all atlas type definitions, only new definitions will be created.
@@ -195,6 +276,8 @@ public class TypesREST {
      * @return A composite wrapper object with lists of type definitions that were successfully
      * created
      * @throws Exception
+     * @HTTP 200 On successful update of requested type definitions
+     * @HTTP 400 On validation failure for any type definitions
      */
     @POST
     @Path("/typedefs")
@@ -211,6 +294,8 @@ public class TypesREST {
      * @param typesDef A composite object that captures all type definition changes
      * @return A composite object with lists of type definitions that were updated
      * @throws Exception
+     * @HTTP 200 On successful update of requested type definitions
+     * @HTTP 400 On validation failure for any type definitions
      */
     @PUT
     @Path("/typedefs")
@@ -227,6 +312,8 @@ public class TypesREST {
      * Bulk delete API for all types
      * @param typesDef A composite object that captures all types to be deleted
      * @throws Exception
+     * @HTTP 204 On successful deletion of the requested type definitions
+     * @HTTP 400 On validation failure for any type definitions
      */
     @DELETE
     @Path("/typedefs")