fineract-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Edward Cable (JIRA)" <j...@apache.org>
Subject [jira] [Created] (FINERACT-422) REST API "live" documentation (Using OpenAPI/Swagger)
Date Mon, 03 Apr 2017 15:34:41 GMT
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)

Mime
View raw message