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 @@
<body>
<head>
<script type="text/javascript">
$( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) }
);
$( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } );
</script>
</head>
<breadcrumbs position="left">
<item name="MetadataGovernance" title="Apache Metadata and Governance"
href="index.html"/>
<item name="MetadataGovernance" title="Apache Metadata and Governance" href="index.html"/>
</breadcrumbs>
<footer>
......
docs/src/site/twiki/index.twiki
......@@ -10,16 +10,22 @@
* Captures Lineage information for data sets and processes
---++ Getting Started
---++ Contents
---++ Documentation
* [[Architecture][High Level Architecture]]
* [[TypeSystem][Type System]]
* [[Repository][Metadata Repository]]
* [[Discovery][Metadata Discovery]]
---++ API Documentation
* <a href="api/rest.html">REST API Documentation</a>
#LicenseInfo
---+ Licensing Information
......
pom.xml
......@@ -869,6 +869,12 @@
</compilerPlugins>-->
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<version>1.29</version>
</plugin>
</plugins>
</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 @@
<fileSet>
<directory>webapp/target/apidocs</directory>
<outputDirectory>apidocs</outputDirectory>
<outputDirectory>docs/api</outputDirectory>
</fileSet>
<fileSet>
......
webapp/pom.xml
......@@ -147,7 +147,6 @@
</dependencies>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
......@@ -161,12 +160,10 @@
<goal>jar</goal>
</goals>
<configuration>
<includeTransitiveDependencySources>false
</includeTransitiveDependencySources>
<includeTransitiveDependencySources>false</includeTransitiveDependencySources>
<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
<dependencySourceInclude>org.apache.hadoop.metadata:*
</dependencySourceInclude>
<dependencySourceInclude>org.apache.hadoop.metadata:*</dependencySourceInclude>
</dependencySourceIncludes>
</configuration>
</execution>
......@@ -220,6 +217,23 @@
</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>
<artifactId>keytool-maven-plugin</artifactId>
<executions>
......@@ -330,6 +344,5 @@
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/AdminResource.java
......@@ -40,6 +40,11 @@ public class AdminResource {
private Response version;
/**
* Fetches the thread stack dump for this application.
*
* @return json representing the thread stack dump.
*/
@GET
@Path("stack")
@Produces(MediaType.TEXT_PLAIN)
......@@ -62,6 +67,11 @@ public class AdminResource {
return builder.toString();
}
/**
* Fetches the version for this application.
*
* @return json representing the version.
*/
@GET
@Path("version")
@Produces(MediaType.APPLICATION_JSON)
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/EntityResource.java
......@@ -70,6 +70,11 @@ public class EntityResource {
this.metadataService = metadataService;
}
/**
* Submits an entity definition (instance) corresponding to a given type.
*
* @param typeName name of a type which is unique.
*/
@POST
@Path("submit/{typeName}")
@Consumes(MediaType.APPLICATION_JSON)
......@@ -93,6 +98,11 @@ public class EntityResource {
}
}
/**
* Fetch the complete definition of an entity given its GUID.
*
* @param guid GUID for the entity
*/
@GET
@Path("definition/{guid}")
@Produces(MediaType.APPLICATION_JSON)
......@@ -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
@Path("list/{entityType}")
@Produces(MediaType.APPLICATION_JSON)
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/MetadataDiscoveryResource.java
......@@ -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.
* @return JSON representing the type and results.
......@@ -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
@Path("search/dsl")
@Produces(MediaType.APPLICATION_JSON)
......@@ -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
@Path("search/gremlin")
@Produces(MediaType.APPLICATION_JSON)
......@@ -183,7 +195,6 @@ public class MetadataDiscoveryResource {
* edgesToFollow = comma-separated list of Labels to follow. Sample query:
* http://host/api/metadata/discovery/search/relationships/1?depth=3&edgesToFollow=Likes,Has
*/
@GET
@Path("/search/relationships/{guid}")
@Produces({MediaType.APPLICATION_JSON})
......@@ -225,8 +236,9 @@ public class MetadataDiscoveryResource {
*
* Sample query:
* 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
@Path("/search/fulltext")
@Produces({MediaType.APPLICATION_JSON})
......@@ -272,7 +284,6 @@ public class MetadataDiscoveryResource {
*
* No parameters taken.
*/
@GET
@Path("/getIndexedFields")
@Produces({MediaType.APPLICATION_JSON})
......
webapp/src/main/java/org/apache/hadoop/metadata/web/resources/TypesResource.java
......@@ -47,6 +47,8 @@ import java.util.List;
*
* A type is the description of any representable item;
* e.g. a Hive table
*
* You could represent any meta model representing any domain using these types.
*/
@Path("types")
@Singleton
......@@ -61,6 +63,12 @@ public class TypesResource {
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
@Path("submit/{typeName}")
@Consumes(MediaType.APPLICATION_JSON)
......@@ -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
@Path("definition/{typeName}")
@Produces(MediaType.APPLICATION_JSON)
......@@ -111,6 +124,9 @@ public class TypesResource {
}
}
/**
* Gets the list of types registed in the type system.
*/
@GET
@Path("list")
@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