diff --git a/docs/developers/swagger/client.md b/docs/developers/swagger/client.md index 8bf163beb..71cdc4d5b 100644 --- a/docs/developers/swagger/client.md +++ b/docs/developers/swagger/client.md @@ -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. diff --git a/fineract-provider/build.gradle b/fineract-provider/build.gradle index 6dd016361..24e09ffcb 100644 --- a/fineract-provider/build.gradle +++ b/fineract-provider/build.gradle @@ -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]) - } - } -} diff --git a/fineract-provider/config/swagger/config.json.template b/fineract-provider/config/swagger/config.json.template deleted file mode 100644 index 8506fa1be..000000000 --- a/fineract-provider/config/swagger/config.json.template +++ /dev/null @@ -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" -} diff --git a/fineract-provider/config/swagger/templates/README.mustache b/fineract-provider/config/swagger/templates/README.mustache deleted file mode 100644 index 1bd3f271d..000000000 --- a/fineract-provider/config/swagger/templates/README.mustache +++ /dev/null @@ -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 - - {{{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 deleted file mode 100644 index 6b5008316..000000000 --- a/fineract-provider/config/swagger/templates/api_doc.mustache +++ /dev/null @@ -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}} - -# **{{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/gradle-wrapper.properties.mustache b/fineract-provider/config/swagger/templates/gradle-wrapper.properties.mustache deleted file mode 100644 index c3d5b65e0..000000000 --- a/fineract-provider/config/swagger/templates/gradle-wrapper.properties.mustache +++ /dev/null @@ -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 diff --git a/fineract-provider/config/swagger/templates/pom.mustache b/fineract-provider/config/swagger/templates/pom.mustache deleted file mode 100644 index 1fb5f19e3..000000000 --- a/fineract-provider/config/swagger/templates/pom.mustache +++ /dev/null @@ -1,355 +0,0 @@ - - 4.0.0 - {{groupId}} - {{artifactId}} - jar - Fineract Client - {{artifactVersion}} - {{artifactUrl}} - {{artifactDescription}} - - {{scmConnection}} - {{scmDeveloperConnection}} - {{scmUrl}} - - - - - {{licenseName}} - {{licenseUrl}} - repo - - - - - - {{developerName}} - {{developerEmail}} - {{developerOrganization}} - {{developerOrganizationUrl}} - - - - - - - org.apache.maven.plugins - maven-enforcer-plugin - 3.0.0-M1 - - - enforce-maven - - enforce - - - - - 2.2.0 - - - - - - - - org.apache.maven.plugins - maven-surefire-plugin - 2.12 - - - - loggerPath - conf/log4j.properties - - - -Xms512m -Xmx1500m - methods - pertest - - - - maven-dependency-plugin - - - package - - copy-dependencies - - - ${project.build.directory}/lib - - - - - - - - org.apache.maven.plugins - maven-jar-plugin - 2.2 - - - - jar - test-jar - - - - - - - - - org.codehaus.mojo - build-helper-maven-plugin - 1.10 - - - add_sources - generate-sources - - add-source - - - - - src/main/java - - - - - add_test_sources - generate-test-sources - - add-test-source - - - - - src/test/java - - - - - - - org.apache.maven.plugins - maven-javadoc-plugin - 3.2.0 - - - attach-javadocs - - jar - - - - - - org.apache.maven.plugins - maven-source-plugin - 2.2.1 - - - attach-sources - - jar-no-fork - - - - - - - - - - sign-artifacts - - - - org.apache.maven.plugins - maven-gpg-plugin - 1.5 - - - sign-artifacts - verify - - sign - - - - - - - - - - - - io.swagger.core.v3 - swagger-annotations - ${swagger-core-version} - - - com.squareup.retrofit2 - converter-gson - ${retrofit-version} - - - com.squareup.retrofit2 - retrofit - ${retrofit-version} - - - com.squareup.retrofit2 - converter-scalars - ${retrofit-version} - - - org.apache.oltu.oauth2 - org.apache.oltu.oauth2.client - ${oltu-version} - - - io.gsonfire - gson-fire - ${gson-fire-version} - - {{#joda}} - - joda-time - joda-time - ${jodatime-version} - - {{/joda}} - {{#threetenbp}} - - org.threeten - threetenbp - ${threetenbp-version} - - {{/threetenbp}} - {{#useRxJava}} - - io.reactivex - rxjava - ${rxjava-version} - - - com.squareup.retrofit2 - adapter-rxjava - ${retrofit-version} - - {{/useRxJava}} - {{#useRxJava2}} - - io.reactivex.rxjava2 - rxjava - ${rxjava-version} - - - com.squareup.retrofit2 - adapter-rxjava2 - ${retrofit-version} - - {{/useRxJava2}} - - {{#usePlayWS}} - - - com.squareup.retrofit2 - converter-jackson - ${retrofit-version} - - - com.fasterxml.jackson.core - jackson-core - ${jackson-version} - - - com.fasterxml.jackson.core - jackson-annotations - ${jackson-version} - - - com.fasterxml.jackson.core - jackson-databind - ${jackson-version} - - - com.fasterxml.jackson.datatype - jackson-datatype-{{^java8}}joda{{/java8}}{{#java8}}jsr310{{/java8}} - ${jackson-version} - - {{#withXml}} - - - - com.fasterxml.jackson.dataformat - jackson-dataformat-xml - ${jackson-version} - - - {{/withXml}} - - com.typesafe.play - play-java-ws_2.11 - ${play-version} - - {{/usePlayWS}} - - {{#parcelableModel}} - - - com.google.android - android - 4.1.1.4 - provided - - {{/parcelableModel}} - - - - junit - junit - ${junit-version} - test - - - - UTF-8 - {{#java8}}1.8{{/java8}}{{^java8}}1.7{{/java8}} - ${java.version} - ${java.version} - 1.8.0 - 2.0.0 - {{#usePlayWS}} - {{#play24}} - 2.10.1 - 2.4.11 - {{/play24}} - {{#play25}} - 2.10.1 - 2.5.15 - {{/play25}} - {{/usePlayWS}} - 2.3.0 - {{#useRxJava}} - 1.3.0 - {{/useRxJava}} - {{#useRxJava2}} - 2.1.1 - {{/useRxJava2}} - {{#joda}} - 2.9.9 - {{/joda}} - {{#threetenbp}} - 1.3.5 - {{/threetenbp}} - 1.0.2 - 4.12 - - \ No newline at end of file