Uploaded image for project: 'Apache Fineract'
  1. Apache Fineract
  2. FINERACT-422

REST API "live" documentation (Using OpenAPI/Swagger)



    • New Feature
    • Status: Resolved
    • Major
    • Resolution: Fixed
    • None
    • 1.2.0
    • SDK


      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)


      • 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


        Issue Links



              nazeer1100126 Nazeer Shaik
              edcable Ed Cable
              0 Vote for this issue
              5 Start watching this issue