hadoop-yarn-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Yang (JIRA)" <j...@apache.org>
Subject [jira] [Created] (YARN-7220) Use apidoc for REST API documentation
Date Tue, 19 Sep 2017 21:23:00 GMT
Eric Yang created YARN-7220:
-------------------------------

             Summary: Use apidoc for REST API documentation
                 Key: YARN-7220
                 URL: https://issues.apache.org/jira/browse/YARN-7220
             Project: Hadoop YARN
          Issue Type: Improvement
          Components: 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: yarn-issues-unsubscribe@hadoop.apache.org
For additional commands, e-mail: yarn-issues-help@hadoop.apache.org


Mime
View raw message