[jira] [Commented] (NIFI-292) Replace/Update REST API documentation generator

["Matt Gilman (JIRA)" <ji...@apache.org>]

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

Matt Gilman commented on NIFI-292:
----------------------------------

Considered other options. The most appealing one seems to be swagger [1]. It provides a for specification for describing a REST API. The latest specification is 2.0. However, the tooling around that specification is still in development [2][3]. We could utilize the 1.2 specification however, the tooling built around it is implemented in scala and requires an unacceptable amount of transitive dependencies [4]. This is being addressed for swagger-core version 1.5.0 [2]. Once this has been released it could be integrated into our application. However, I would prefer to use the maven plugin to generate the API description and documentation at build time [5].

Both of these efforts appear to be under active development. However, if this continues to drag on I would consider another alternative. 

[1] http://swagger.io/
[2] https://github.com/swagger-api/swagger-core
[3] https://github.com/kongchen/swagger-maven-plugin/tree/dev2.0
[4] https://github.com/swagger-api/swagger-core/issues/624
[5] https://github.com/kongchen/swagger-maven-plugin/wiki/Swagger-Maven-Plugin

> Replace/Update REST API documentation generator
> -----------------------------------------------
>
>                 Key: NIFI-292
>                 URL: https://issues.apache.org/jira/browse/NIFI-292
>             Project: Apache NiFi
>          Issue Type: Improvement
>          Components: Core Framework, Core UI
>            Reporter: Matt Gilman
>            Assignee: Matt Gilman
>
> Currently, we use enunciate to generate our REST API documentation. As part of the generated docs, a JS library with a questionable license is included. 
> Consider updating the usage to use a custom Freemarker Transform as specified here:
> http://docs.codehaus.org/display/ENUNCIATE/Applying+a+Custom+Skin+to+Enunciate%27s+Documentation
> or switching to another solution altogether.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)