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

["Santosh Math (JIRA)" <ji...@apache.org>]

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

Santosh Math resolved FINERACT-422.
-----------------------------------
    Resolution: Fixed

> 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: Shaik Nazeer Hussain
>            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)