REST API Live Documentation Using Swagger

Actively being worked on as an Apache Fineract project for Google Summer of Code 2017.

Target release	TBD
Epic
Project Status	DESIGN/KICKOFF PHASE
Designer	Sanyam Goel
Developers	Sanyam Goel
Mentors	Aleksandar Vidakovic
Product Management	Aleksandar Vidakovic
QA	Santosh Math

Goals

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.

Impact:

Easier to consume Mifos REST API for front-end/mobile etc. developers.

Timelines / Schedule

Interval	Tasks
Community Bonding Period ( 4th May - 30 May )
4 May - 15 May	Understanding Swagger, SpringFox Sorting Swagger components - Swagger UI, Swagger Editor
16 May - 2 June	End Semester University Exams
Coding Period : Phase I ( 30 May - 15 June )
	Redefine previous code and add neccessary dependencies and spring java configuration. Develop v1 for testing the approach on sample Api written in spring and configuring Swagger on the API Mapping the HTTP response code and testing.
Coding Period : Phase II ( 16 June - 30 June )
	Integrating Swagger into the project and Verification . Auto generation Swagger file from code annotations. Adding any additional dependencies and take feedback from community and mentor.
Coding Period : Phase III ( 1 July - 15 July )
	Enabling Springfox’s Swagger UI. Advanced Configuration of Swagger mainly centers around the Docket bean. Filtering API for Swagger’s Response by passing parameters to the apis() and paths() methods of the Docket class.
Coding Period : Phase IV ( 1 July - 15 July )
	Usage of Swagger descriptor to generate client libraries. Add paragraph to new REST API explaining the importation of latest Mifos Swagger into Postman to show the import success message and scheduling.
Coding Period : Phase V ( 31 July - 10 August )
	To make sure that test is written for every possible component. Experiment with the test written in the previous weeks for the final time to confirm that they are not buggy. Take some feedback from the community. Working on the bugs and other function as well.
Coding Period : Phase VI ( 10 August - 21 August )
	Buffer days in order to accommodate any pending/overdue tasks from previous weeks.