[
https://issues.apache.org/jira/browse/HADOOP-14888?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16173975#comment-16173975
]
Allen Wittenauer commented on HADOOP-14888:
-------------------------------------------
Sorry, I wasn't every clear. It was more of a statement of fact than any
implication on your goals here.
My only request for any end result here is that they continue to be
readable/findable outside of javadoc, since the two audiences are very
different.
> 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
>
> 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]
