[ 
https://issues.apache.org/jira/browse/FINERACT-422?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Edward Cable updated FINERACT-422:
----------------------------------
    Fix Version/s: 1.2.0

> 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
>            Priority: Major
>              Labels: gsoc2017
>             Fix For: 1.2.0
>
>
> 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
(v7.6.3#76005)

Reply via email to