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 149 additions and 16 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
...@@ -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,7 +147,6 @@ ...@@ -147,7 +147,6 @@
</dependencies> </dependencies>
<build> <build>
<pluginManagement>
<plugins> <plugins>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
...@@ -161,12 +160,10 @@ ...@@ -161,12 +160,10 @@
<goal>jar</goal> <goal>jar</goal>
</goals> </goals>
<configuration> <configuration>
<includeTransitiveDependencySources>false <includeTransitiveDependencySources>false</includeTransitiveDependencySources>
</includeTransitiveDependencySources>
<includeDependencySources>true</includeDependencySources> <includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes> <dependencySourceIncludes>
<dependencySourceInclude>org.apache.hadoop.metadata:* <dependencySourceInclude>org.apache.hadoop.metadata:*</dependencySourceInclude>
</dependencySourceInclude>
</dependencySourceIncludes> </dependencySourceIncludes>
</configuration> </configuration>
</execution> </execution>
...@@ -220,6 +217,23 @@ ...@@ -220,6 +217,23 @@
</plugin> </plugin>
<plugin> <plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>docs</goal>
</goals>
</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>
<plugin>
<groupId>org.codehaus.mojo</groupId> <groupId>org.codehaus.mojo</groupId>
<artifactId>keytool-maven-plugin</artifactId> <artifactId>keytool-maven-plugin</artifactId>
<executions> <executions>
...@@ -330,6 +344,5 @@ ...@@ -330,6 +344,5 @@
</executions> </executions>
</plugin> </plugin>
</plugins> </plugins>
</pluginManagement>
</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