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)
