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: [email protected]
For additional commands, e-mail: [email protected]
