[jira] [Created] (FINERACT-422) REST API "live" documentation (Using OpenAPI/Swagger)

["Edward Cable (JIRA)" <ji...@apache.org>]

Edward Cable created FINERACT-422:
-------------------------------------

             Summary: REST API "live" documentation (Using OpenAPI/Swagger)
                 Key: FINERACT-422
                 URL: https://issues.apache.org/jira/browse/FINERACT-422
             Project: Apache Fineract
          Issue Type: New Feature
            Reporter: Edward Cable
            Assignee: Markus Geiss


Mifos (Fineract) of course has a documented REST API already. It currently has two limitations:
It's source is simply a HTML file that is maintained manually in parallel to the source code which actually defines the REST API, and therefore can be out of sync
It's not "live", that is one currently has set up a REST tool such as e.g. Postman & Co. to "explore" it; contrary to the approach you can see e.g. on the Swagger Petstore example and (increasingly) other sites offering REST APIs.
The goal of this project is address this by using Swagger (now Open API Initiative OAI), most probably combined with SpringFox in for Mifos (Fineract), and replace the current apiLive.htm.
Phase II: once the Swagger live documentation is working it would be interesting to use the Swagger descriptor to generate client libraries (e. g. Java, Angular2). Nice to have optional add-on ideas for the end of the project: Add a paragraph to this new REST API Doc explaining how to easily import the (latest) Mifos Swagger into Postman, and perhaps add a Run in Postman button?
Someone suggested a potential alternative to using Swagger & SpringFox may be to instead use Spring REST Docs; if you feel that is better suite to fulfill the requirements above, please do feel free to explain this to your mentor and pursue in that direction.

UPDATE: this idea might be swapped to focus on doing the same task but for the new forthcoming generation 3 architecture (Apache Fineract 2.0 at https://github.com/mifosio)

Tasks:

* familiarize yourself with Swagger + SpringFox
* create working v1 code demonstrating feasibility of approach
* propose it to the community (mailing list), and react to feedback
* don't lose any documentation that's already on the current (manual) REST API doc, maintain it's human readable comments (by moving that into JavaDoc/annotations in code which SpringFox/Swagger exploit), the "sections", etc.

See also https://mifosforge.jira.com/browse/MIFOSX-2699



--
This message was sent by Atlassian JIRA
(v6.3.15#6346)