[ https://issues.apache.org/jira/browse/HADOOP-14888?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Allen Wittenauer updated HADOOP-14888: -------------------------------------- Component/s: build > 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: common-issues-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-issues-h...@hadoop.apache.org