Saturday, April 30, 2016

Mifos Live Documentation

I first used Mashery iodocs in Winter 2014 when doing a project at WhiteHat Security, Santa Clara. When I look at Mifos in the light of this experience, I realised a tool like iodocs supplies an important missing piece in the Mifos eco-system - Live Documentation. Further, I'd say this could accelerate the development of apps on top of the Apache Fineract platform and spur the project into the future. Here's a quick intro to iodocs:


The key to Technology empowered Financial Inclusion is an Open, Democratic, Helpful Community with dedicated full-time Technology Partners that can Deploy and Support solutions for MFI's with a host of applications both Web-based and Mobile. One of the keys to speedy, efficient and cost-effective Application Development is to minimize the dependency on multiple external tools which hinder Programmer Productivity.

To address this challenge, one of the proposed projects for GSOC 2016 was Live Documentation. But even before GSOC selection process started, back at the Techdays in Amsterdam, I had the opportunity to co-organize a hackathon and teamed up with Antony Omeri from OmexIT, Kenya and started the iodocs effort to supply this. On returning to base, I took out a few hours to write a Perl script that parser the source code and generates iodocs documentation for all of the Fineract API's. The script takes as input, the base folder of a Jersey REST Application and outputs a JSON formatted as per iodocs syntactic and semantic structure.

Currently, since the Fineract project is based on java Spring framework and Jersey using gradle as a build tool. The hope is for the Live Documentation to be available by July-August 2016. While it remains to be seen how the Spring docs based solution progresses, we at SanJose Solutions decided to put up our version of the Live Docs at:


Some FAQs:
1. Why did you work on this project though there was a GSOC project for the same task?

The simple answer is we didn't want to wait that long! Our own current project is dependent upon one of the recent additions to the Fineract platform and I met several other application developers at the Techdays and realized that this will benefit lots of App developers and make it much easier for people just getting started working with a REST API like Fineract.

2. Why were iodocs and Perl chosen?

The choice of software and programming language was purely practical considerations. Since Fineract code follows the Jersey framework, it is consistent and easy to get key information about the API from the @Path and the method type (GET/POST/PUT/DELETE) annotations. Having past experience with iodocs and Perl, I realized that I could quickly hack together a script in a few hours to parse and generate the documentation. Finally, it's lot more fun programming in a scripting language which excels at regexes and parsing, so Perl was the automatic choice.

3. How usable is this and are there any future improvements with this Live Documentation?

We have currently tested query functions but write operations like create (POST) and edit (PUT) are currently lacking an easy way to pass JSON in the body. We are planning to address this gap soon.

4. Since Fineract is a Java based software with gradle build tool and the core developers already have little time to maintain a Perl based solution, what about documenting future versions of the platform?

Running the script does require Perl installed on the system but it is available on all platforms. Though Linux and Mac OSX come with Perl preinstalled, on Windows its not so hard to get it (Strawberry Perl). However, the reason we think it's maintainable is because it takes a few minutes and level 0 sysadmin skills to run the script once it's setup properly. So we are happy to do this from time to time and update the above URL.

---

So if you're working on any app on the fineract platform REST API, you now can try out the API using just your browser (without a REST client). Though the official API docs has most of the necessary documentation and provides excellent details, iodocs provides a complementary function - quick accessible live documentation which you can try. So go ahead and check it out!

P.S: If it prompts you for a username and password, just hit Enter (leave the user/pass fields empty)

No comments:

Post a Comment