[
https://issues.apache.org/jira/browse/HADOOP-14888?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Eric Yang updated HADOOP-14888:
-------------------------------
Attachment: HADOOP-14888.001.patch
Add apidoc to superpom. Any project that like to use apidoc can start using
apidoc annotation. The generated document will be in
project.build.directory/rest-docs. Rest-docs can be aggregated by site
document if desired.
> Use apidoc for REST API documentation
> -------------------------------------
>
> Key: HADOOP-14888
> URL: https://issues.apache.org/jira/browse/HADOOP-14888
> Project: Hadoop Common
> Issue Type: Improvement
> Components: build, documentation
> Reporter: Eric Yang
> Assignee: Eric Yang
> Attachments: HADOOP-14888.001.patch
>
>
> There are more REST API being developed in Hadoop, and it would be great to
> standardize on the method of generate REST API document.
> There are several method done today:
> Swagger YAML
> Javadoc
> Wiki pages
> JIRA comments
> The most frequently used method is JIRA comments and Wiki pages. Both
> methods are prone to data loss through passage of time. We will need a more
> effortless approach to maintain REST API documentation. Swagger YAML can
> also be out of sync with reality, if new methods are added to java code
> directly. Javadoc annotation seems like a good approach to maintain REST API
> document. Both Jersey and Atlassian community has maven plugin to help
> generating REST API document, but those maven plugins have ceased to
> function. After searching online for REST API documentation for a bit,
> [apidoc|http://apidocjs.com/] is one library that stand out. This could be
> the ideal approach to manage Hadoop REST API document. It supports javadoc
> like annotations, and generate beautiful schema changes documentation.
> If this is accepted, I will add apidoc installation to dev-support
> Dockerfile, and pom.xml changes for javadoc plugin to ignore the custom tags.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
