From 1d0d7c1bd8d20b10fa67743ceaa7372ce603278e Mon Sep 17 00:00:00 2001
From: Chinmay Kulkarni <30969403+Grandolf49@users.noreply.github.com>
Date: Thu, 27 Aug 2020 02:22:30 +0530
Subject: [PATCH] FINERACT-1133 Added Mustache templates for documentation of
generated library
---
.../config/swagger/templates/README.mustache | 109 ++++++++++++++++++
.../config/swagger/templates/api_doc.mustache | 81 +++++++++++++
.../config/swagger/templates/pom.mustache | 2 +-
3 files changed, 191 insertions(+), 1 deletion(-)
create mode 100644 fineract-provider/config/swagger/templates/README.mustache
create mode 100644 fineract-provider/config/swagger/templates/api_doc.mustache
diff --git a/fineract-provider/config/swagger/templates/README.mustache b/fineract-provider/config/swagger/templates/README.mustache
new file mode 100644
index 000000000..1bd3f271d
--- /dev/null
+++ b/fineract-provider/config/swagger/templates/README.mustache
@@ -0,0 +1,109 @@
+# Fineract Client
+
+This is a Java and Retrofit2 based client library for [Apache Fineract Platform](https://github.com/apache/fineract) version `{{appVersion}}`. This library is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen).
+
+{{#appDescription}}{{{appDescription}}}{{/appDescription}}
+
+{{#infoUrl}}
+ For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+
+## Add Dependency
+
+To add the library as dependency to your project, follow the steps below.
+
+### Maven
+
+Add this dependency to your project's POM:
+
+```xml
+
+ {{{groupId}}}
+ {{{artifactId}}}
+ {{{artifactVersion}}}
+ compile
+
+```
+
+### Gradle
+
+Add this dependency to your project's build file:
+
+```groovy
+implementation "{{{groupId}}}:{{{artifactId}}}:{{{artifactVersion}}}"
+```
+
+## Build Project
+
+To build the API client library locally, you must have:
+1. Java 1.8+
+2. Maven/Gradle
+
+To install the API client library to your local Maven repository, execute:
+
+```shell
+mvn clean install
+```
+
+To build the JAR, execute:
+
+```shell
+mvn clean package
+```
+
+## Getting Started
+
+Once you have added the library, you can use the following example **Java** code for authentication.
+
+```java
+import com.google.gson.JsonObject;
+import org.apache.fineract.client.models.PostAuthenticationResponse;
+import org.apache.fineract.client.services.AuthenticationHttpBasicApi;
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class Example {
+
+ public static void main(String[] args) {
+
+ // Using API Key Authorization "tenantid"
+ ApiClient defaultClient = new ApiClient("tenantid");
+ defaultClient.setApiKey("default");
+
+ AuthenticationHttpBasicApi apiService = defaultClient.createService(AuthenticationHttpBasicApi.class);
+
+ // Response body
+ JsonObject jsonObject = new JsonObject();
+ jsonObject.addProperty("username", "mifos");
+ jsonObject.addProperty("password", "password");
+
+ Call call = apiService.authenticate(jsonObject.toString());
+ call.enqueue(new Callback() {
+ @Override
+ public void onResponse(Call call
+ , Response response) {
+ System.out.println(call.toString() + "\n" + response.toString());
+ }
+
+ @Override
+ public void onFailure(Call call, Throwable t) {
+ System.out.println(t.getMessage());
+ }
+ });
+ }
+}
+
+```
+
+For complete documentation, refer `docs/AuthenticationHttpBasicApi.md`
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.
+
+## Author
+
+{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}
+{{/hasMore}}{{/apis}}{{/apiInfo}}
\ No newline at end of file
diff --git a/fineract-provider/config/swagger/templates/api_doc.mustache b/fineract-provider/config/swagger/templates/api_doc.mustache
new file mode 100644
index 000000000..6b5008316
--- /dev/null
+++ b/fineract-provider/config/swagger/templates/api_doc.mustache
@@ -0,0 +1,81 @@
+# {{classname}}{{#description}}
+{{description}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+
+# **{{operationId}}**
+> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
+
+{{summary}}{{#notes}}
+
+{{notes}}{{/notes}}
+
+### Example
+```java
+{{#hasAuthMethods}}
+ApiClient defaultClient = new ApiClient();
+
+{{#authMethods}}{{#isBasic}}
+// Uncomment this if you want to use HTTP basic authorization: "{{{name}}}"
+//defaultClient = new ApiClient("{{{name}}}");
+//defaultClient.setCredentials("YOUR USERNAME", "YOUR PASSWORD");{{/isBasic}}{{#isApiKey}}
+
+// API Key Authorization: "{{{name}}}"
+// USE THIS IF YOU ARE TESTING THE LIBRARY
+defaultClient = new ApiClient("{{{name}}}");
+defaultClient.setApiKey("default");
+
+// Uncomment this if you are using OAuth2 access token for authorization: "{{{name}}}"
+//OAuth {{{name}}} = (OAuth) defaultClient.getAuthentication("{{{name}}}");
+//{{{name}}}.setAccessToken("YOUR ACCESS TOKEN");{{/isApiKey}}
+{{/authMethods}}
+{{/hasAuthMethods}}
+
+{{classname}} apiService = defaultClient.createService({{classname}}.class);
+
+// Initialize these parameters earlier.
+Call<{{returnType}}> call = apiService.{{operationId}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}});
+call.enqueue(new Callback<{{returnType}}>() {
+ @Override
+ public void onResponse(Call<{{returnType}}> call, Response<{{returnType}}> response) {
+ System.out.println(call.toString() + "\n" + response.toString());
+ }
+
+ @Override
+ public void onFailure(Call<{{returnType}}> call, Throwable t) {
+ System.out.println(t.getMessage());
+ }
+});
+
+```
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#@last}}
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------{{/@last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{defaultValue}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^@last}}, {{/@last}}{{/values}}]{{/allowableValues}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{returnType}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../README.md#{{name}}){{^@last}}, {{/@last}}{{/authMethods}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{/operation}}
+{{/operations}}
\ No newline at end of file
diff --git a/fineract-provider/config/swagger/templates/pom.mustache b/fineract-provider/config/swagger/templates/pom.mustache
index e1fce2663..1fb5f19e3 100644
--- a/fineract-provider/config/swagger/templates/pom.mustache
+++ b/fineract-provider/config/swagger/templates/pom.mustache
@@ -4,7 +4,7 @@
{{groupId}}
{{artifactId}}
jar
- {{artifactId}}
+ Fineract Client
{{artifactVersion}}
{{artifactUrl}}
{{artifactDescription}}