Skip to content

A
atlas
Commit ac67d212 by Venkatesh Seetharam
Options

BUG-32605 Generate docs for REST API. Contributed by Venkatesh Seetharam

parent a4a57644
Showing with 329 additions and 196 deletions
docs/src/site/site.xml
...@@ -53,14 +53,12 @@ ...@@ -53,14 +53,12 @@
<body> <body>
<head> <head>
<script type="text/javascript"> <script type="text/javascript">
$( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } $( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } );
);
</script> </script>
</head> </head>
<breadcrumbs position="left"> <breadcrumbs position="left">
<item name="MetadataGovernance" title="Apache Metadata and Governance" <item name="MetadataGovernance" title="Apache Metadata and Governance" href="index.html"/>
href="index.html"/>
</breadcrumbs> </breadcrumbs>
<footer> <footer>
......
docs/src/site/twiki/index.twiki
...@@ -10,16 +10,22 @@ ...@@ -10,16 +10,22 @@
* Captures Lineage information for data sets and processes * Captures Lineage information for data sets and processes
---++ Getting Started ---++ Getting Started
---++ Contents ---++ Documentation
* [[Architecture][High Level Architecture]] * [[Architecture][High Level Architecture]]
* [[TypeSystem][Type System]] * [[TypeSystem][Type System]]
* [[Repository][Metadata Repository]] * [[Repository][Metadata Repository]]
* [[Discovery][Metadata Discovery]] * [[Discovery][Metadata Discovery]]
---++ API Documentation
* <a href="api/rest.html">REST API Documentation</a>
#LicenseInfo #LicenseInfo
---+ Licensing Information ---+ Licensing Information
......
pom.xml
...@@ -851,12 +851,12 @@ ...@@ -851,12 +851,12 @@
<jvmArg>-XX:MaxPermSize=128m</jvmArg> <jvmArg>-XX:MaxPermSize=128m</jvmArg>
</jvmArgs> </jvmArgs>
<!-- <!--
<javacArgs> <javacArgs>
<javacArg>-source</javacArg> <javacArg>-source</javacArg>
<javacArg>${java.version}</javacArg> <javacArg>${java.version}</javacArg>
<javacArg>-target</javacArg> <javacArg>-target</javacArg>
<javacArg>${java.version}</javacArg> <javacArg>${java.version}</javacArg>
</javacArgs> </javacArgs>
--> -->
<!-- The following plugin is required to use quasiquotes in Scala 2.10 and is used <!-- The following plugin is required to use quasiquotes in Scala 2.10 and is used
by Spark SQL for code generation. --> by Spark SQL for code generation. -->
...@@ -869,6 +869,12 @@ ...@@ -869,6 +869,12 @@
</compilerPlugins>--> </compilerPlugins>-->
</configuration> </configuration>
</plugin> </plugin>
<plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<version>1.29</version>
</plugin>
</plugins> </plugins>
</pluginManagement> </pluginManagement>
......
src/build/enunciate.xml 0 → 100644
<!--
~ Licensed to the Apache Software Foundation (ASF) under one
~ or more contributor license agreements. See the NOTICE file
~ distributed with this work for additional information
~ regarding copyright ownership. The ASF licenses this file
~ to you under the Apache License, Version 2.0 (the
~ "License"); you may not use this file except in compliance
~ with the License. You may obtain a copy of the License at
~
~ http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<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.hadoop.metadata.web.resources.*"/>
<services>
<rest defaultRestSubcontext="/api/metadata/">
<custom-resource-parameter-annotation
qualifiedName="org.glassfish.jersey.media.multipart.FormDataParam"/>
</rest>
</services>
<webapp disabled="true"/>
<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"/>
</modules>
</enunciate>
\ No newline at end of file
src/main/assemblies/standalone-package.xml
...@@ -37,7 +37,7 @@ ...@@ -37,7 +37,7 @@
<fileSet> <fileSet>
<directory>webapp/target/apidocs</directory> <directory>webapp/target/apidocs</directory>
<outputDirectory>apidocs</outputDirectory> <outputDirectory>docs/api</outputDirectory>
</fileSet> </fileSet>
<fileSet> <fileSet>
......
webapp/pom.xml
...@@ -147,189 +147,202 @@ ...@@ -147,189 +147,202 @@
</dependencies> </dependencies>
<build> <build>
<pluginManagement> <plugins>
<plugins> <plugin>
<plugin> <groupId>org.apache.maven.plugins</groupId>
<groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId>
<artifactId>maven-javadoc-plugin</artifactId> <executions>
<executions> <execution>
<execution> <id>uber-javadocs</id>
<id>uber-javadocs</id> <phase>site</phase>
<phase>site</phase> <goals>
<goals> <goal>javadoc</goal>
<goal>javadoc</goal> <goal>jar</goal>
<goal>jar</goal> </goals>
</goals> <configuration>
<configuration> <includeTransitiveDependencySources>false</includeTransitiveDependencySources>
<includeTransitiveDependencySources>false <includeDependencySources>true</includeDependencySources>
</includeTransitiveDependencySources> <dependencySourceIncludes>
<includeDependencySources>true</includeDependencySources> <dependencySourceInclude>org.apache.hadoop.metadata:*</dependencySourceInclude>
<dependencySourceIncludes> </dependencySourceIncludes>
<dependencySourceInclude>org.apache.hadoop.metadata:* </configuration>
</dependencySourceInclude> </execution>
</dependencySourceIncludes> </executions>
</configuration> </plugin>
</execution>
</executions>
</plugin>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId> <artifactId>maven-war-plugin</artifactId>
<version>2.4</version> <version>2.4</version>
<configuration> <configuration>
<webResources> <webResources>
<resource> <resource>
<directory>../dashboard/v1</directory> <directory>../dashboard/v1</directory>
<targetPath>dashboard</targetPath> <targetPath>dashboard</targetPath>
</resource> </resource>
<resource> <resource>
<directory>../dashboard/v2</directory> <directory>../dashboard/v2</directory>
<targetPath>dashboard/v2</targetPath> <targetPath>dashboard/v2</targetPath>
</resource> </resource>
<resource> <resource>
<directory>src/main/webapp/WEB-INF</directory> <directory>src/main/webapp/WEB-INF</directory>
<targetPath>WEB-INF</targetPath> <targetPath>WEB-INF</targetPath>
</resource> </resource>
</webResources> </webResources>
</configuration> </configuration>
</plugin> </plugin>
<plugin> <plugin>
<artifactId>maven-resources-plugin</artifactId> <artifactId>maven-resources-plugin</artifactId>
<version>2.6</version> <version>2.6</version>
<executions> <executions>
<execution> <execution>
<id>copy-resources</id> <id>copy-resources</id>
<phase>validate</phase> <phase>validate</phase>
<goals> <goals>
<goal>copy-resources</goal> <goal>copy-resources</goal>
</goals> </goals>
<configuration> <configuration>
<outputDirectory>${project.build.directory}/webapps <outputDirectory>${project.build.directory}/webapps
</outputDirectory> </outputDirectory>
<resources> <resources>
<resource> <resource>
<directory>src/conf</directory> <directory>src/conf</directory>
<filtering>true</filtering> <filtering>true</filtering>
</resource> </resource>
</resources> </resources>
</configuration> </configuration>
</execution> </execution>
</executions> </executions>
</plugin> </plugin>
<plugin> <plugin>
<groupId>org.codehaus.mojo</groupId> <groupId>org.codehaus.enunciate</groupId>
<artifactId>keytool-maven-plugin</artifactId> <artifactId>maven-enunciate-plugin</artifactId>
<executions> <executions>
<execution> <execution>
<id>clean</id> <goals>
<phase>generate-resources</phase> <goal>docs</goal>
<goals> </goals>
<goal>clean</goal> </execution>
</goals> </executions>
</execution> <configuration>
<execution> <!-- the directory where to put the docs -->
<id>genkey</id> <docsDir>${project.build.directory}/apidocs</docsDir>
<phase>generate-resources</phase> <configFile>${basedir}/../src/build/enunciate.xml</configFile>
<goals> </configuration>
<goal>generateKeyPair</goal> </plugin>
</goals>
</execution>
</executions>
<configuration>
<dname>cn=metadata.incubator.apache.org</dname>
<keystore>${project.build.directory}/metadata.keystore</keystore>
<keypass>metadata-passwd</keypass>
<storepass>metadata-passwd</storepass>
<alias>metadata</alias>
<keyalg>RSA</keyalg>
<validity>100000</validity>
</configuration>
</plugin>
<plugin> <plugin>
<groupId>org.mortbay.jetty</groupId> <groupId>org.codehaus.mojo</groupId>
<artifactId>maven-jetty-plugin</artifactId> <artifactId>keytool-maven-plugin</artifactId>
<version>${jetty.version}</version> <executions>
<configuration> <execution>
<skip>${skipITs}</skip> <id>clean</id>
<!--only skip int tests --> <phase>generate-resources</phase>
<connectors> <goals>
<!-- <goal>clean</goal>
<connector implementation="org.mortbay.jetty.security.SslSocketConnector"> </goals>
<port>21443</port> </execution>
<maxIdleTime>60000</maxIdleTime> <execution>
<keystore>${project.build.directory}/../../webapp/target/metadata.keystore</keystore> <id>genkey</id>
<keyPassword>metadata-passwd</keyPassword> <phase>generate-resources</phase>
<password>metadata-passwd</password> <goals>
</connector> <goal>generateKeyPair</goal>
--> </goals>
<connector </execution>
implementation="org.mortbay.jetty.nio.SelectChannelConnector"> </executions>
<port>21000</port> <configuration>
<maxIdleTime>60000</maxIdleTime> <dname>cn=metadata.incubator.apache.org</dname>
</connector> <keystore>${project.build.directory}/metadata.keystore</keystore>
</connectors> <keypass>metadata-passwd</keypass>
<webApp>${project.build.directory}/metadata-webapp-${project.version} <storepass>metadata-passwd</storepass>
</webApp> <alias>metadata</alias>
<contextPath>/</contextPath> <keyalg>RSA</keyalg>
<useTestClasspath>true</useTestClasspath> <validity>100000</validity>
<systemProperties> </configuration>
<systemProperty> </plugin>
<name>hadoop.conf.dir</name>
<value>${project.build.directory}/webapps/hadoop/conf</value> <plugin>
</systemProperty> <groupId>org.mortbay.jetty</groupId>
<systemProperty> <artifactId>maven-jetty-plugin</artifactId>
<name>hadoop.tmp.dir</name> <version>${jetty.version}</version>
<value>${project.build.directory}/tmp-hadoop-${user.name}</value> <configuration>
</systemProperty> <skip>${skipITs}</skip>
<systemProperty> <!--only skip int tests -->
<name>hadoop.log.dir</name> <connectors>
<value>${project.build.directory}/logs</value> <!--
</systemProperty> <connector implementation="org.mortbay.jetty.security.SslSocketConnector">
<systemProperty> <port>21443</port>
<name>system.lib.location</name> <maxIdleTime>60000</maxIdleTime>
<value>${project.build.directory}/dependency</value> <keystore>${project.build.directory}/../../webapp/target/metadata.keystore</keystore>
</systemProperty> <keyPassword>metadata-passwd</keyPassword>
<systemProperty> <password>metadata-passwd</password>
<name>keystore.file</name> </connector>
<value> -->
${project.build.directory}/../../webapp/target/metadata.keystore <connector
</value> implementation="org.mortbay.jetty.nio.SelectChannelConnector">
</systemProperty> <port>21000</port>
<systemProperty> <maxIdleTime>60000</maxIdleTime>
<name>truststore.file</name> </connector>
<value> </connectors>
${project.build.directory}/../../webapp/target/metadata.keystore <webApp>${project.build.directory}/metadata-webapp-${project.version}
</value> </webApp>
</systemProperty> <contextPath>/</contextPath>
</systemProperties> <useTestClasspath>true</useTestClasspath>
<stopKey>metadata-stop</stopKey> <systemProperties>
<stopPort>41001</stopPort> <systemProperty>
</configuration> <name>hadoop.conf.dir</name>
<executions> <value>${project.build.directory}/webapps/hadoop/conf</value>
<execution> </systemProperty>
<id>start-jetty</id> <systemProperty>
<phase>pre-integration-test</phase> <name>hadoop.tmp.dir</name>
<goals> <value>${project.build.directory}/tmp-hadoop-${user.name}</value>
<goal>run</goal> </systemProperty>
</goals> <systemProperty>
<configuration> <name>hadoop.log.dir</name>
<daemon>true</daemon> <value>${project.build.directory}/logs</value>
</configuration> </systemProperty>
</execution> <systemProperty>
<execution> <name>system.lib.location</name>
<id>stop-jetty</id> <value>${project.build.directory}/dependency</value>
<phase>post-integration-test</phase> </systemProperty>
<goals> <systemProperty>
<goal>stop</goal> <name>keystore.file</name>
</goals> <value>
</execution> ${project.build.directory}/../../webapp/target/metadata.keystore
</executions> </value>
</plugin> </systemProperty>
</plugins> <systemProperty>
</pluginManagement> <name>truststore.file</name>
<value>
${project.build.directory}/../../webapp/target/metadata.keystore
</value>
</systemProperty>
</systemProperties>
<stopKey>metadata-stop</stopKey>
<stopPort>41001</stopPort>
</configuration>
<executions>
<execution>
<id>start-jetty</id>
<phase>pre-integration-test</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<daemon>true</daemon>
</configuration>
</execution>
<execution>
<id>stop-jetty</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build> </build>
</project> </project>
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/AdminResource.java
...@@ -40,6 +40,11 @@ public class AdminResource { ...@@ -40,6 +40,11 @@ public class AdminResource {
private Response version; private Response version;
/**
* Fetches the thread stack dump for this application.
*
* @return json representing the thread stack dump.
*/
@GET @GET
@Path("stack") @Path("stack")
@Produces(MediaType.TEXT_PLAIN) @Produces(MediaType.TEXT_PLAIN)
...@@ -62,6 +67,11 @@ public class AdminResource { ...@@ -62,6 +67,11 @@ public class AdminResource {
return builder.toString(); return builder.toString();
} }
/**
* Fetches the version for this application.
*
* @return json representing the version.
*/
@GET @GET
@Path("version") @Path("version")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/EntityResource.java
...@@ -70,6 +70,11 @@ public class EntityResource { ...@@ -70,6 +70,11 @@ public class EntityResource {
this.metadataService = metadataService; this.metadataService = metadataService;
} }
/**
* Submits an entity definition (instance) corresponding to a given type.
*
* @param typeName name of a type which is unique.
*/
@POST @POST
@Path("submit/{typeName}") @Path("submit/{typeName}")
@Consumes(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON)
...@@ -93,6 +98,11 @@ public class EntityResource { ...@@ -93,6 +98,11 @@ public class EntityResource {
} }
} }
/**
* Fetch the complete definition of an entity given its GUID.
*
* @param guid GUID for the entity
*/
@GET @GET
@Path("definition/{guid}") @Path("definition/{guid}")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
...@@ -123,6 +133,13 @@ public class EntityResource { ...@@ -123,6 +133,13 @@ public class EntityResource {
} }
} }
/**
* Gets the list of entities for a given entity type.
*
* @param entityType name of a type which is unique
* @param offset starting offset for pagination
* @param resultsPerPage number of results for pagination
*/
@GET @GET
@Path("list/{entityType}") @Path("list/{entityType}")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/MetadataDiscoveryResource.java
...@@ -73,7 +73,7 @@ public class MetadataDiscoveryResource { ...@@ -73,7 +73,7 @@ public class MetadataDiscoveryResource {
} }
/** /**
* Search using query DSL. * Search using a given query.
* *
* @param query search query in raw gremlin or DSL format falling back to full text. * @param query search query in raw gremlin or DSL format falling back to full text.
* @return JSON representing the type and results. * @return JSON representing the type and results.
...@@ -114,6 +114,12 @@ public class MetadataDiscoveryResource { ...@@ -114,6 +114,12 @@ public class MetadataDiscoveryResource {
} }
} }
/**
* Search using query DSL format.
*
* @param dslQuery search query in DSL format.
* @return JSON representing the type and results.
*/
@GET @GET
@Path("search/dsl") @Path("search/dsl")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
...@@ -141,6 +147,12 @@ public class MetadataDiscoveryResource { ...@@ -141,6 +147,12 @@ public class MetadataDiscoveryResource {
} }
} }
/**
* Search using raw gremlin query format.
*
* @param gremlinQuery search query in raw gremlin format.
* @return JSON representing the type and results.
*/
@GET @GET
@Path("search/gremlin") @Path("search/gremlin")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
...@@ -183,7 +195,6 @@ public class MetadataDiscoveryResource { ...@@ -183,7 +195,6 @@ public class MetadataDiscoveryResource {
* edgesToFollow = comma-separated list of Labels to follow. Sample query: * edgesToFollow = comma-separated list of Labels to follow. Sample query:
* http://host/api/metadata/discovery/search/relationships/1?depth=3&edgesToFollow=Likes,Has * http://host/api/metadata/discovery/search/relationships/1?depth=3&edgesToFollow=Likes,Has
*/ */
@GET @GET
@Path("/search/relationships/{guid}") @Path("/search/relationships/{guid}")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
...@@ -225,8 +236,9 @@ public class MetadataDiscoveryResource { ...@@ -225,8 +236,9 @@ public class MetadataDiscoveryResource {
* *
* Sample query: * Sample query:
* http://host/api/metadata/discovery/search/fulltext?depth=1&property=Name&text=Zack * http://host/api/metadata/discovery/search/fulltext?depth=1&property=Name&text=Zack
*
* Comma separated list of types as qeury.
*/ */
// Comma separated list of types as qeury.
@GET @GET
@Path("/search/fulltext") @Path("/search/fulltext")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
...@@ -272,7 +284,6 @@ public class MetadataDiscoveryResource { ...@@ -272,7 +284,6 @@ public class MetadataDiscoveryResource {
* *
* No parameters taken. * No parameters taken.
*/ */
@GET @GET
@Path("/getIndexedFields") @Path("/getIndexedFields")
@Produces({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON})
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/TypesResource.java
...@@ -47,6 +47,8 @@ import java.util.List; ...@@ -47,6 +47,8 @@ import java.util.List;
* *
* A type is the description of any representable item; * A type is the description of any representable item;
* e.g. a Hive table * e.g. a Hive table
*
* You could represent any meta model representing any domain using these types.
*/ */
@Path("types") @Path("types")
@Singleton @Singleton
...@@ -61,6 +63,12 @@ public class TypesResource { ...@@ -61,6 +63,12 @@ public class TypesResource {
this.metadataService = metadataService; this.metadataService = metadataService;
} }
/**
* Submits a type definition corresponding to a given type representing a meta model of a
* domain. Could represent things like Hive Database, Hive Table, etc.
*
* @param typeName name of a type, should be unique.
*/
@POST @POST
@Path("submit/{typeName}") @Path("submit/{typeName}")
@Consumes(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON)
...@@ -86,6 +94,11 @@ public class TypesResource { ...@@ -86,6 +94,11 @@ public class TypesResource {
} }
} }
/**
* Fetch the complete definition of a given type name which is unique.
*
* @param typeName name of a type which is unique.
*/
@GET @GET
@Path("definition/{typeName}") @Path("definition/{typeName}")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
...@@ -111,6 +124,9 @@ public class TypesResource { ...@@ -111,6 +124,9 @@ public class TypesResource {
} }
} }
/**
* Gets the list of types registed in the type system.
*/
@GET @GET
@Path("list") @Path("list")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment