Skip to content

Instantly share code, notes, and snippets.

@kangbreder kangbreder/GSoC'19.md
Last active Oct 1, 2019

Embed
What would you like to do?

GOOGLE SUMMER OF CODES 2019 FINAL REPORT

Organisation: THE APACHE SOFTWARE FOUNDATION

Project Name: SWAGGER DOCUMENTATION OF FINERACT APIs

Mentor: Sanyam Goel

Student: Kang Breder

PROJECT OVERVIEW

One of the most powerful aspects of the Apache Fineract platform and the Mifos X solution stack built on top of it, is the full set of APIs that are available to enable any third party to build new financial inclusion solutions on the platform. It is truly open source core banking software from the ground up. As part of an Apache Fineract project for GSOC in 2017, all of the API docs were converted from manually-generated API docs to live API docs based on the Swagger/OpenAPI format. Moving from the manually generated API docs to this live format would enable all the benefits such as easier testing through live examples, improved standardization, better sharing and portability, and increased automation of API-related processes.

However since 2017, new APIs have been added and have not been documented in the swagger format. Also additional task like ability to run test from Swagger UI itself, saving json during build, leveraging swagger codegen for generation of client libraries and reflecting entity description on Swagger UI itself needed to be done.

During this GSoC period, I worked to improve the current swagger document and Swagger UI.

Link to Fineract Jira Ticket: Click here

Project Github Repository

Working Repository: Click here

Project Goals

  1. Complete Swagger documentation on all API’s of Fineract[COMPLETED]
  2. Description inside of swagger docs[COMPLETED]
  3. Try it out button for API’s from swagger-UI[IN PROGRESS]
  4. Automatically generate the swagger-docs -> building with Fineract[IN PROGRESS]
  5. Navigation Bar on swagger-UI(For easy access of documentation of API's)[NOT COMPLETED]
  6. Migrating the complete overview section in swagger-docs/swagger-docs[NOT COMPLETED]
  7. Swagger guide for new Api’s or how to add a swagger doc to any Fineract API[COMPLETED]
  8. QA round to check if all the API’s are reflecting or not(Correct)[IN PROGRESS]

Project Implementation

Task1: Complete Swagger documentation on all API’s of Fineract[COMPLETED]

The remaining APIs of fineract have been documented to swagger format. For Example:

  • Adhoc query API
  • New self service APIs
  • Pockets API
  • Search API
  • Self Run Report API
  • Audits API

Example Screenshots

search

selfaccount

Task2: Description inside of Swagger Docs[COMPLETED]

Detailed description for the following APIs are now reflected on the Swagger UI

  • Accounting APIs
  • Adhocquery API
  • Batch APIs
  • Commands APIs
  • Infrastructure APIs
  • Mix APIs
  • Notification API
  • Organisation APIs
  • Portfolio APIs
  • Spm APIs
  • Template APIs
  • User Administration APIs

Example Screenshots

desbest

des2

des3

batchdes

Field descriptions for Loans API have been carried over to swagger UI.

Task3: Try it out button for API’s from swagger-UI[IN PROGRESS]

For the Try It Out button to send client request and fetch response from the server, header parameters for Authorisation and Fineract-Platform-TenantId needed to be added to every request as it is done on Postman.

Problems Faced

  • It was difficult finding a definite solution for adding these header params on the whole resource using html. A number of approaches were implemented but none worked. The final way was to add these headers on all endpoints using swagger-annotations.

Example Screenshots

head1

head2

param5

  • Another problem faced here was that Swagger UI could not have access to the resources when request were sent even when the additional headers were added. On the console, the headers were present but all the headers were converted to lower cases. This is could propbably be an issue with Swagger's UI javascript. This issue is yet to be resolved.

Task4: Automatically generate the swagger-docs -> building with Fineract[IN PROGRESS]

I have used swagger-gradle-plugin for saving the json during build and added a task resolve which Resolves project openAPI specification and saves the result in JSON in /src/main/resources/swagger-ui. But after adding this task, upon running ./gradlew resolve i got a build failed with an exception. I have sent this to the mailing list but have not yet received any assistance till now.

Task5: Navigation Bar on swagger-UI(For easy access of documentation of API's)[NOT COMPLETED]

For copying the complete overview section over to the Swagger UI, a navigation bar needed to be included as the complete overview section is quite lengthly. So i started working on the navigation bar first. From all researches I made, for our project, a navigation bar could be implemented using a React js. And this can only be done using multiple specification files. There will be no way to create hyperlinks on the navigation bar without having multiple specification files. But swagger-core can only generate a single spec file during runtime which is the swagger.json. Because of this, I had made to proposal to Ed and Sanyam that we create several specification files which groups related APIs using swagger inspector and host them on swaggerhub. And we could be able to create nav bar with each hyperlink pointing to a spec file that groups related APIs for easy access of APIs by developers using React. This was really going to be time consuming to start generating APIs all over before using in a react Application.

Link to related smartbear article used:Click here

Task6: Migrating the complete overview section in swagger-docs/swagger-docs[NOT COMPLETED]

The Overview section on apiLive.htm will be carried over to the Swagger document in a navigation bar as the overivew section is lengthly. Without a navigation bar, this overview section if present on Swagger UI will make it more difficult to go through the various APIs listed on the UI.

Task7: Swagger guide for new Api’s or how to add a swagger doc to any Fineract API [COMPLETED]

Link to the guide: Click here

Task8: QA round to check if all the API’s are reflecting or not(Correct)[IN PROGRESS]

I have gone through some of the APIs on the codebase to check if they properly reflect on Swagger UI. I am still to continue going through the APIs to see if they correctly display.

Generating Client Libraries from Swagger Specification File

Task generateSwaggerCode was added to fineract which will automatically generate Code in a specified language using gradle-swagger-generator-plugin.

How to generate client code using task generateSwaggerCode

Go to build.gradle and find the following script

swaggerSources { fineract { inputFile = file('src/main/resources/swagger-ui/response.json') code { language = 'java' } } }

You can change the language from java to any other language of your choice, save and on your terminal, Run

./gradlew generateSwaggerCode

The task generates source code into build/swagger-code-fineract. To see the models, navigate to **build/swagger-code-fineract/src/main/java/io/swagger/client/model

Below is an example of java code generate using task generateSwaggerCode

model

Work Left

  • Continue implementation of additional headers on Swagger UI for enabling sending of request from the UI itself.
  • Fix task resolve failure to enable automatic save of json.
  • Navigation bar on Swagger UI.

Action Plan

It has been exciting working on the project. Post GSoC, I plan to continue contributing to the swagger documentation project and continue implemetation of the features currently in progress and those left to be completed. I will have to discuss further with the community concerning the Navigation bar feature and Try It Out button so that I can continue working on those tasks.

Link to Pull Request

Pull request: Click here

Conclusion

Contributing to The Apache Fineract Foundation has been an amazing experience. As a new developer, I have learned a lot from the Apache Fineract community and have improved on my coding skills especially while working with the swagger documentation of the APIs. These three months have been quite hectic and stressful due to the lots of researches in order to implement some the above listed features, but was worth it. I have also improved on my researching and googling skills and these will help me later on in future as an Engineer and Open Source Contributor. I am very sorry i was not able to complete the project during my three months tenure due to circumstances beyond my control as the solutions to implement some of these features turned out to be complicated with the large set of APIs Fineract has got and how Fineract works. I will be glad to stay and keep contributing to the Apache Fineract Project especially to continue working on the swagger documentation project. I will like to thank The Apache Software Foundation and especially Edward Cable (CEO of Mifos Initiative) for giving me this opportunity. Finally, I would like to say "Thank You" to my mentor Sanyam Goel who has guided me through till the end of this Summer Internship.

Email: kangbreder@gmail.com

Github: https://github.com/kangbreder

LinkedIn: https://www.linkedin.com/in/kang-breder-9a575b186/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.