This gist contains the details about My GSoC '20 Project with The Mifos Initiative. During GSoC, I worked on architecting and developing the Mifos Android SDK, integrating Swagger Codegen in Apache Fineract project and releasing the Fineract Client API Library for using it in Android Applications of Mifos.
In all the Android Applications of Mifos, android-client, mifos-mobile, mobile-wallet there is a lot of repeated code which deals with interacting with the Fineract APIs. This can be optimized and be moved into a single library which can be just added as a dependency to the projects. This will save a lot of code and facilitate independent testing. In GSoC, I worked on implementing this.
- To develop an architecture of the Android SDK which serves the purpose of abstracting all the API calls and other things that an app developer should not be concerned about.
- To provide extensive testing coverage for the SDK.
- To decouple the android applications wherever possible in order to support module testing.
- To integrate Swagger Codegen in Apache Fineract Project.
- To release the library so that Android Applications can use it.
- Fineract Client Library is released and can be added in the gradle dependency for Android Applications of Mifos.
- All the API call implementations are abstracted from the developer. So the only concern of the developer is to request the data from SDK and update UI for the user.
- Testing coverage will be provided in the SDK itself.
- Authentication and User management will be handled by SDK.
- The Mifos Android SDK also contains a sample app module that demonstrates the usage of APIs from the library.
During the initial discussions, we decided to build the SDK specifically for Android. So for the 1st Coding Period, I was working on Mifos Android Architecture. The project is purely written in Kotlin. Following are the components of the project:
- Core Module
- This is the main library module that was planned to be released.
- Provides an interface to the user to consume Fineract 1.x APIs
- Provides a simple interface to obtain the response of APIs in Observable or LiveData depending on the user.
- Implemented the standard MVVM Architecture in the library as well.
- User is expected to obtain an instance of MifosSdk.
- Eg.
var mifosSdk = MifosSdk.getInstance()
- Eg.
- The library is initialized implicity, right when the app is launched. ContentProvider takes care of this. So user is not required to initialize library.
- MifosSdk provides functions to obtain the ViewModels of the APIs.
- ViewModels talk to the Repositories requesting it to get response from the APIs.
- Repositories finally initiate API Calls through Services and return the response to the ViewModels.
- Models are responsible to model the API response into Data Classes.
- The response is returned as a Flowable.
- To convert response to Observable:
Flowable<Model>?.toObservable()
- To convert response to LiveData:
Flowable<Model>?.toLiveData()
- App Module
- This contains an example app that demonstrates the usage of the SDK
- It is implemented using the MVVM Architecture.
- Contains a ListView that demonstrates how to consume the APIs and displays the response.
Upon further discussions with mentors, we decided to implement Swagger Codegen for generation of the SDK. Swagger Codegen allows us to generate a client library from an API Specification File. This Spec File is created based on the Open API Specification. We can customize the generate library to suit our needs. Here is the repository for this task.
- Fineract Client Generator
- Swagger Codegen is used to generate a Java and Retrofit2 based Fineract client library.
- We planned to publish it to Maven or Jitpack after which it can be added as a dependency in the Android Projects of Mifos.
- CircleCI Continuous Integration Tool is also implemented which automates the following things:
- Executes the client-generator.sh script to generate the client SDK.
- Builds the generated client library to make sure it does not break.
- Whenever Git Tags are pushed to mark a particular release, CircleCI automatically creates a GitHub Release and publishes the SDK for further use.
- For reference: CircleCI Configuration File
After successfully testing the implementation of Swagger Codegen in finerat-client repository, I started working on Apache Fineract to implement the feature of generating the client library as a Gradle task. This was attempted last year, but the PR was not merged.
Swagger Codegen was successfully integrated in Apache Fineract project. FINERACT-838 is the JIRA Issue for this feature. This feature supports all clients supported by Swagger Codegen. It uses OpenAPI Specification Version 3.0.3.
Note: The client library is generated using the latest source of Apache Fineract project. It may not work as you expected since the version currentlt deployed on demo.mifos.io is 1.0.0 and on demo.fineract.dev is 1.3.0. So always make sure to generate the SDK against the respective deployed version of Fineract.
- Swagger Gradle Plugin - This provides a Gradle task resolve which generates the OpenAPI Spec File of Fineract. This file is later used by Swagger Codegen to generate the client library.
- Configuration JSON File - This file configures the metadata of the generated client. Things like package name, group id, artifact id, artifact description are all configured from this file
- Mustache Templates - These templates are used to customize the generated code according to our needs. If we need to customize or hardcode some specific versions, or if we need to customize the generated documentation, we use the Mustache Templates for this.
- Swagger Codegen - It takes all the above things as input and generates a Client Library for us
- Fineract Client Library - This is the actual client library generated by Swagger Codegen that users can use in their projects.
These are all the Pull Requests merged into the Apache Fineract Project.
- PR-1206 adds Swagger Codegen Support in Apache Fineract project.
- PR-1228 adds build tasks in TravisCI for building and testing the generated client library.
- PR-1270 address the issue FINERACT-1105. Swagger Plugin now generates a valid spec file.
- PR-1271 for FINERACT-1101. Generated code was not building successfully. Used Mustache Templates to address this.
- PR-1272 is a backport PR of PR-1270 for version
1.4.0 - PR-1285 is a backport PR of PR-1271 for version
1.4.0 - PR-1293 for FINERACT-1133. Generated code contained incorrect documentation. Used Mustache Templates to address this.
- PR-1295 is a backport PR of PR-1293 for version
1.4.0
In root directory of the project:
- Run
./gradlew resolve - Run
./gradlew generateSwaggerCode
The client code will be generated under build/swagger-code-fineract
- Run
cd build/swagger-code-fineract - Run
mvn clean packageor./gradlew build
Swagger Codegen provides several options to customize the generated code. Here are the options available for customization.
- Open the config.json.template file
- Customize options
- Build the project again as mentioned in Generate API Client Code section
Swagger Codegen uses Mustache Templates for generating the client library. For additional customizations you can add/edit custom templates inside the fineract-provider/config/swagger/templates folder.
Make sure you are following the supported templates. Otherwise, the generated code will not build correctly.
If you need to add templates for a specific library, you need to follow the same directory structure as present in the links above.
The resolve task in build.gradle file will generate the OpenAPI 3.0.3 Spec File for the project. To make sure Swagger Codegen generates a correct library, it is important for the OpenAPI Spec file to be valid. Use Swagger OpenAPI Validator to validate the spec file.
These are all the JIRA tickets I worked on.
- FINERACT-838 - Swagger generated client libraries
- FINERACT-1100 - Swagger CodeGen WARN i.s.c.v.g.java.AbstractJavaCodegen New (reserved word) cannot be used as model name. Renamed to ModelNew
- FINERACT-1101 - Swagger CodeGen Test Build using Gradle instead of Maven.
- FINERACT-1102 - Swagger Codegen Client JAR should be available on a Maven repo
- FINERACT-1105 - Swagger generates invalid Open API Specification file
- FINERACT-1133 - Swagger generated library contains incorrect documentation
Finally, after testing everything, the fineract client library is now published here. Developers can use it in Android, Java or Kotlin projects. Here is an example to use the library.
Steps:
- Obtain an instance of FineractApiClient
- Create Service
- Consume API
- Handle Response
FineractApiClient apiClient = new FineractApiClient();
AuthenticationHttpBasicApi authApi = apiClient.createService(AuthenticationHttpBasicApi.class);
Call<PostAuthenticationResponse> call = authApi.authenticate("mifos", "password");
call.enqueue(new Callback<PostAuthenticationResponse>() {
@Override
public void onResponse(Call<PostAuthenticationResponse> call, Response<PostAuthenticationResponse> response) {
// Handle Response
}
@Override
public void onFailure(Call<PostAuthenticationResponse> call, Throwable t) {
// Handle Error
}
});For more instructions on how to use the library, read README.md
Google Summer of Code with The Mifos Initiative was the best experience I have had as a student till now. Getting an opportunity to work with highly skilled developers from the community was very overwhelming. I thank my mentors Ishan Khanna and Rajan Maurya for guiding me throughout the Summer in my project. I also thank Ed Cable and the entire community for their active support throughout GSoC '20.
If you want to know more about the project, feel free to contact me here:
- [email protected]
- Gitter - @Grandolf49