hadoop-common-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Yang (JIRA)" <j...@apache.org>
Subject [jira] [Comment Edited] (HADOOP-14888) Use apidoc for REST API documentation
Date Thu, 21 Sep 2017 18:38:02 GMT

    [ https://issues.apache.org/jira/browse/HADOOP-14888?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16175261#comment-16175261
] 

Eric Yang edited comment on HADOOP-14888 at 9/21/17 6:37 PM:
-------------------------------------------------------------

[~aw] Yes, they will be readable and searchable outside of javadoc.  I like to include apidoc
as part of dev-support Dockerfile.  Pre-commit test also needs to have apidoc runnable when
new code includes apidoc annotated javadoc.  What is the proper approach to include apidoc
into pre-commit test?  I think pre-commit test is using Yetus provided Dockerfile, which is
not part of Hadoop code base.


was (Author: eyang):
[~aw] Yes, they will be readable and searchable outside of javadoc.  I like to include apidoc
as part of dev-support Dockerfile.  Pre-commit test also needs to have apidoc runnable when
new code includes apidoc annotated javadoc.  What is the proper approach to include apidoc
into pre-commit test?

> 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-unsubscribe@hadoop.apache.org
For additional commands, e-mail: common-issues-help@hadoop.apache.org


Mime
View raw message