CBSNexora/cbsnexora-backend
4
0
Fork 0
Code Issues Pull Requests Actions 37 Packages Projects Releases Wiki Activity

FINERACT-1207: Clean up fineract-provider/config/swagger following introduction of fineract-client/

Browse Source
This commit is contained in:
Aleksandar Vidakovic
2020-10-19 21:15:50 +03:00
committed by Petri Tuomola
parent db4d2ae006
commit f192b7315b
7 changed files with 6 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developers/swagger/client.md
+6 -34
View File
@@ -1,46 +1,18 @@
Generate Apache Fineract API Client
============
Apache Fineract supports client code generation using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen). Project supports [all clients](https://github.com/swagger-api/swagger-codegen#overview) supported by Swagger Codegen. It uses [OpenAPI Specification Version 3.0.3](https://swagger.io/specification/).
Apache Fineract supports client code generation using [OpenAPI Generator](https://openapi-generator.tech). It uses [OpenAPI Specification Version 3.0.3](https://swagger.io/specification/).
## Generate API Client
In root directory of the project:
The API client is built as part of the overall Fineract Gradle build. If you want to save (maybe) some time you can try to execute just the following line in root directory of the project:
- Run `./gradlew resolve`
- Run `./gradlew generateSwaggerCode`
- Run `./gradlew :fineract-client:build`
The client code will be generated under `build/swagger-code-fineract`
The client JAR can be found in `fineract-client/build/libs`.
## Build API Client
- Run `cd build/swagger-code-fineract`
- Run `./gradlew build`
Alternatively, if you have Maven installed on your system, you can also do:
- Run `cd build/swagger-code-fineract`
- Run `mvn clean package`
## Customize Generated Code
Swagger Codegen provides several options to customize the generated code. [Here](https://openapi-generator.tech/docs/generators/java/) are the options available for customization.
- Open the [config.json.template](https://github.com/apache/fineract/blob/develop/fineract-provider/config/swagger/config.json.template) file
- Customize options
- Build the project again as mentioned in **Generate API Client Code** section
## Customize using Mustache Templates
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.
- [Java Mustache Templates](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources/Java)
- [Retrofit2 Mustache Templates](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources/Java/libraries/retrofit2)
If you need to add templates for a specific library, you need to follow the same directory structure as present in the links above.
Note: Build only `fineract-client` may or may not actually save you some build time. There are still project module dependencies that might trigger a complete build.
## Validate OpenAPI Spec File
The `resolve` task in [build.gradle](https://github.com/apache/fineract/blob/develop/fineract-provider/build.gradle#L212) file will generate the OpenAPI 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](https://validator.swagger.io/) to validate the spec file.
The `resolve` task in [build.gradle](https://github.com/apache/fineract/blob/develop/fineract-provider/build.gradle#L80) file will generate the OpenAPI 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. Validation is done automatically by the OpenAPI code generator Gradle plugin. If you still have problems during code generation please use [Swagger OpenAPI Validator](https://validator.swagger.io/) to validate the spec file.
fineract-provider/build.gradle
-18
View File
@@ -600,21 +600,3 @@ gitProperties {
// make sure the generateGitProperties task always executes (even when git.properties is not changed)
generateGitProperties.outputs.upToDateWhen { false }
task prepareConfigJson(dependsOn: 'generateGitProperties') {
doLast {
def versionForSwagger
if(project.ext.properties.containsKey("gitProps"))
versionForSwagger = project.ext.gitProps['git.commit.id.describe']
else
versionForSwagger = "unknown"
copy {
from file('config/swagger/config.json.template')
into file('config/swagger')
rename { String filename -> return 'config.json' }
filter(ReplaceTokens, tokens: [VERSION: versionForSwagger])
}
}
}
fineract-provider/config/swagger/config.json.template
-12
View File
@@ -1,12 +0,0 @@
{
"groupId": "org.apache.fineract",
"artifactId": "client",
"artifactVersion": "@VERSION@",
"invokerPackage": "org.apache.fineract.client",
"modelPackage": "org.apache.fineract.client.models",
"apiPackage": "org.apache.fineract.client.services",
"artifactDescription": "A Java and Retrofit2 based client library for Apache Fineract Platform",
"dateLibrary": "java8",
"hideGenerationTimestamp": "true",
"library": "retrofit2"
}
fineract-provider/config/swagger/templates/README.mustache
-109
View File
@@ -1,109 +0,0 @@
# 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
<dependency>
<groupId>{{{groupId}}}</groupId>
<artifactId>{{{artifactId}}}</artifactId>
<version>{{{artifactVersion}}}</version>
<scope>compile</scope>
</dependency>
```
### 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<PostAuthenticationResponse> call = apiService.authenticate(jsonObject.toString());
call.enqueue(new Callback<PostAuthenticationResponse>() {
@Override
public void onResponse(Call<PostAuthenticationResponse> call
, Response<PostAuthenticationResponse> response) {
System.out.println(call.toString() + "\n" + response.toString());
}
@Override
public void onFailure(Call<PostAuthenticationResponse> 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}}
fineract-provider/config/swagger/templates/api_doc.mustache
-81
View File
@@ -1,81 +0,0 @@
# {{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}}
<a name="{{operationId}}"></a>
# **{{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}}
fineract-provider/config/swagger/templates/gradle-wrapper.properties.mustache
-6
View File
@@ -1,6 +0,0 @@
#Tue May 17 23:08:05 CST 2016
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-6.6-bin.zip
fineract-provider/config/swagger/templates/pom.mustache
-355
View File
@@ -1,355 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>{{groupId}}</groupId>
<artifactId>{{artifactId}}</artifactId>
<packaging>jar</packaging>
<name>Fineract Client</name>
<version>{{artifactVersion}}</version>
<url>{{artifactUrl}}</url>
<description>{{artifactDescription}}</description>
<scm>
<connection>{{scmConnection}}</connection>
<developerConnection>{{scmDeveloperConnection}}</developerConnection>
<url>{{scmUrl}}</url>
</scm>
<licenses>
<license>
<name>{{licenseName}}</name>
<url>{{licenseUrl}}</url>
<distribution>repo</distribution>
</license>
</licenses>
<developers>
<developer>
<name>{{developerName}}</name>
<email>{{developerEmail}}</email>
<organization>{{developerOrganization}}</organization>
<organizationUrl>{{developerOrganizationUrl}}</organizationUrl>
</developer>
</developers>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.0.0-M1</version>
<executions>
<execution>
<id>enforce-maven</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<requireMavenVersion>
<version>2.2.0</version>
</requireMavenVersion>
</rules>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.12</version>
<configuration>
<systemProperties>
<property>
<name>loggerPath</name>
<value>conf/log4j.properties</value>
</property>
</systemProperties>
<argLine>-Xms512m -Xmx1500m</argLine>
<parallel>methods</parallel>
<forkMode>pertest</forkMode>
</configuration>
</plugin>
<plugin>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/lib</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<!-- attach test jar -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.2</version>
<executions>
<execution>
<goals>
<goal>jar</goal>
<goal>test-jar</goal>
</goals>
</execution>
</executions>
<configuration>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.10</version>
<executions>
<execution>
<id>add_sources</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>
src/main/java</source>
</sources>
</configuration>
</execution>
<execution>
<id>add_test_sources</id>
<phase>generate-test-sources</phase>
<goals>
<goal>add-test-source</goal>
</goals>
<configuration>
<sources>
<source>
src/test/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>sign-artifacts</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<dependencies>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger-core-version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-gson</artifactId>
<version>${retrofit-version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>${retrofit-version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-scalars</artifactId>
<version>${retrofit-version}</version>
</dependency>
<dependency>
<groupId>org.apache.oltu.oauth2</groupId>
<artifactId>org.apache.oltu.oauth2.client</artifactId>
<version>${oltu-version}</version>
</dependency>
<dependency>
<groupId>io.gsonfire</groupId>
<artifactId>gson-fire</artifactId>
<version>${gson-fire-version}</version>
</dependency>
{{#joda}}
<dependency>
<groupId>joda-time</groupId>
<artifactId>joda-time</artifactId>
<version>${jodatime-version}</version>
</dependency>
{{/joda}}
{{#threetenbp}}
<dependency>
<groupId>org.threeten</groupId>
<artifactId>threetenbp</artifactId>
<version>${threetenbp-version}</version>
</dependency>
{{/threetenbp}}
{{#useRxJava}}
<dependency>
<groupId>io.reactivex</groupId>
<artifactId>rxjava</artifactId>
<version>${rxjava-version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>adapter-rxjava</artifactId>
<version>${retrofit-version}</version>
</dependency>
{{/useRxJava}}
{{#useRxJava2}}
<dependency>
<groupId>io.reactivex.rxjava2</groupId>
<artifactId>rxjava</artifactId>
<version>${rxjava-version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>adapter-rxjava2</artifactId>
<version>${retrofit-version}</version>
</dependency>
{{/useRxJava2}}
{{#usePlayWS}}
<!-- JSON processing: jackson -->
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-jackson</artifactId>
<version>${retrofit-version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${jackson-version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${jackson-version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson-version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.datatype</groupId>
<artifactId>jackson-datatype-{{^java8}}joda{{/java8}}{{#java8}}jsr310{{/java8}}</artifactId>
<version>${jackson-version}</version>
</dependency>
{{#withXml}}
<!-- XML processing: Jackson -->
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-xml</artifactId>
<version>${jackson-version}</version>
</dependency>
{{/withXml}}
<dependency>
<groupId>com.typesafe.play</groupId>
<artifactId>play-java-ws_2.11</artifactId>
<version>${play-version}</version>
</dependency>
{{/usePlayWS}}
{{#parcelableModel}}
<!-- Needed for Parcelable support-->
<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>4.1.1.4</version>
<scope>provided</scope>
</dependency>
{{/parcelableModel}}
<!-- test dependencies -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit-version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>{{#java8}}1.8{{/java8}}{{^java8}}1.7{{/java8}}</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
<maven.compiler.target>${java.version}</maven.compiler.target>
<gson-fire-version>1.8.0</gson-fire-version>
<swagger-core-version>2.0.0</swagger-core-version>
{{#usePlayWS}}
{{#play24}}
<jackson-version>2.10.1</jackson-version>
<play-version>2.4.11</play-version>
{{/play24}}
{{#play25}}
<jackson-version>2.10.1</jackson-version>
<play-version>2.5.15</play-version>
{{/play25}}
{{/usePlayWS}}
<retrofit-version>2.3.0</retrofit-version>
{{#useRxJava}}
<rxjava-version>1.3.0</rxjava-version>
{{/useRxJava}}
{{#useRxJava2}}
<rxjava-version>2.1.1</rxjava-version>
{{/useRxJava2}}
{{#joda}}
<jodatime-version>2.9.9</jodatime-version>
{{/joda}}
{{#threetenbp}}
<threetenbp-version>1.3.5</threetenbp-version>
{{/threetenbp}}
<oltu-version>1.0.2</oltu-version>
<junit-version>4.12</junit-version>
</properties>
</project>