FINERACT-835: Upgrade Swagger and automatically generate the JSON spec (#1069)

Co-authored-by: Michael Vorburger ⛑️ <mike@vorburger.ch>

README.md

@@ -251,6 +251,8 @@ Apache Fineract Platform API
 
 The API for the Fineract-platform (project named 'Apache Fineract') is documented in the API-docs under <b><i>Full API Matrix</i></b> and can be viewed [here](https://demo.fineract.dev/fineract-provider/api-docs/apiLive.htm "API Documentation").
 
+If you have your own Fineract instance running, you can find the same documentation under '(your host:port)/fineract-provider/api-docs/apiLive.htm' under your. The Swagger documentation (work in progress) can be accessed under '(your host:port)/fineract-provider/swagger-ui/index.html'
+
 
 API clients (Web UIs, Mobile, etc.)
 ============

fineract-provider/build.gradle

@@ -49,6 +49,7 @@ buildscript {
         classpath "gradle.plugin.com.gorylenko.gradle-git-properties:gradle-git-properties:2.2.2"
         classpath "net.ltgt.gradle:gradle-errorprone-plugin:1.2.1"
         classpath "com.diffplug.spotless:spotless-plugin-gradle:4.4.0"
+        classpath "io.swagger.core.v3:swagger-gradle-plugin:2.1.2"
     }
 }
 
@@ -71,7 +72,7 @@ apply plugin: 'jacoco'
 apply plugin: "com.gorylenko.gradle-git-properties"
 apply plugin: "net.ltgt.errorprone"
 apply plugin: "com.diffplug.gradle.spotless"
-// apply plugin: 'pmd'
+apply plugin: "io.swagger.core.v3.swagger-gradle-plugin"
 
 dependencyManagement {
     imports {
@@ -114,6 +115,9 @@ dependencyManagement {
         dependency 'com.github.spotbugs:spotbugs-annotations:4.0.4'
         dependency 'javax.cache:cache-api:1.1.1'
 
+        // If this is upgraded, you need to change path in WebFrontEndConfiguration
+        dependency 'org.webjars.npm:swagger-ui-dist:3.26.0'
+
         dependency ('org.dom4j:dom4j:2.1.3') {
             exclude 'relaxngDatatype:relaxngDatatype' // already in com.sun.xml.bind:jaxb-osgi:2.3.0.1
             // FINERACT-940 && FINERACT-966 https://github.com/spotbugs/spotbugs/issues/1128
@@ -181,6 +185,18 @@ openjpa {
     }
 }
 
+// Configuration for Swagger documentation generation task
+// https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-gradle-plugin
+resolve {
+    outputFileName = 'fineract'
+    outputFormat = 'JSON'
+    prettyPrint = 'TRUE'
+    classpath = sourceSets.main.runtimeClasspath
+    outputDir = file("${buildDir}/classes/java/main/static/swagger-ui")
+}
+
+// Configuration for JaCoCo code coverage task
+// https://www.eclemma.org/jacoco/
 jacoco {
     toolVersion = jacocoVersion
     reportsDir = file("$buildDir/reports/jacoco")
@@ -244,6 +260,8 @@ spotless {
     lineEndings 'UNIX'
 }
 
+// Configuration for Apache Release Audit Tool task
+// https://github.com/eskatos/creadur-rat-gradle
 rat {
     verbose = false
     reportDir = new File(buildDir,'reports/rat')
@@ -274,7 +292,7 @@ rat {
         '**/NOTICE_RELEASE',
         '**/NOTICE_SOURCE',
         // Swagger License
-        '**/src/main/resources/swagger-ui/**',
+        '**/src/main/resources/static/swagger-ui/**',
         // gradle
         '**/.gradle/**',
         '**/gradlew',
@@ -522,6 +540,7 @@ modernizer {
 compileJava{
     dependsOn rat
     dependsOn spotlessCheck
+    finalizedBy resolve
 }
 /*
 pmd {
@@ -556,7 +575,7 @@ license {
         "**/*.mustache",
         "**/package-info.java",
         "**/keystore.jks",
-        "**/swagger-ui/**",
+        "**/static/swagger-ui/**",
         "**/api-docs/**",
     ])
     strictCheck true

fineract-provider/dependencies.gradle

@@ -76,7 +76,7 @@ dependencies {
 
              'javax.cache:cache-api',
 
-             'com.github.spotbugs:spotbugs-annotations',
+             'com.github.spotbugs:spotbugs-annotations'
     )
     implementation ('io.swagger:swagger-jersey-jaxrs') {
         exclude group: 'javax.validation'
@@ -108,6 +108,7 @@ dependencies {
     runtimeOnly(
             'org.apache.bval:org.apache.bval.bundle',
             'org.springframework.boot:spring-boot-starter-actuator',
+            'org.webjars.npm:swagger-ui-dist',
 
             // Although fineract (at the time of writing) doesn't have any compile time dep. on httpclient,
             // it's useful to have this for the Spring Boot TestRestTemplate http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#boot-features-rest-templates-test-utility

fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/boot/WebFrontEndConfiguration.java

@@ -34,5 +34,11 @@ public class WebFrontEndConfiguration implements WebMvcConfigurer {
         if (!registry.hasMappingForPattern("/**")) {
             registry.addResourceHandler("/**").addResourceLocations(CLASSPATH_RESOURCE_LOCATIONS);
         }
+
+        // TODO: The below path should be version agnostic
+        String[] SWAGGER_RESOURCE_LOCATIONS = { "classpath:/static/swagger-ui/",
+                "classpath:/META-INF/resources/webjars/swagger-ui-dist/3.26.0/" };
+
+        registry.addResourceHandler("/swagger-ui/**").addResourceLocations(SWAGGER_RESOURCE_LOCATIONS);
     }
 }

fineract-provider/src/main/resources/static/swagger-ui/index.html

@@ -0,0 +1,60 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+    <style>
+      html
+      {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+
+      *,
+      *:before,
+      *:after
+      {
+        box-sizing: inherit;
+      }
+
+      body
+      {
+        margin:0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script src="./swagger-ui-bundle.js"> </script>
+    <script src="./swagger-ui-standalone-preset.js"> </script>
+    <script>
+    window.onload = function() {
+      // Begin Swagger UI call region
+      const ui = SwaggerUIBundle({
+        url: "response.json",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      })
+      // End Swagger UI call region
+
+      window.ui = ui
+    }
+  </script>
+  </body>
+</html>

fineract-provider/src/main/resources/swagger-ui/index.html

@@ -1,95 +0,0 @@
-<!-- HTML for static distribution bundle build -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Swagger UI</title>
-  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
-  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
-  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
-  <style>
-    html
-    {
-        box-sizing: border-box;
-        overflow: -moz-scrollbars-vertical;
-        overflow-y: scroll;
-    }
-    *,
-    *:before,
-    *:after
-    {
-        box-sizing: inherit;
-    }
-
-    body {
-      margin:0;
-      background: #fafafa;
-    }
-  </style>
-</head>
-
-<body>
-
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
-  <defs>
-    <symbol viewBox="0 0 20 20" id="unlocked">
-          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="locked">
-      <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="close">
-      <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="large-arrow">
-      <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="large-arrow-down">
-      <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
-    </symbol>
-
-
-    <symbol viewBox="0 0 24 24" id="jump-to">
-      <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 24 24" id="expand">
-      <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
-    </symbol>
-
-  </defs>
-</svg>
-
-<div id="swagger-ui"></div>
-
-<script src="./swagger-ui-bundle.js"> </script>
-<script src="./swagger-ui-standalone-preset.js"> </script>
-<script>
-window.onload = function() {
-  // Build a system
-  const ui = SwaggerUIBundle({
-    // url: "http://petstore.swagger.io/v2/swagger.json",
-    // spec: "/home/sanyam/Desktop/newSwagger/swagger-ui/dist/response.json"
-    url: "response.json",
-    dom_id: '#swagger-ui',
-    presets: [
-      SwaggerUIBundle.presets.apis,
-      SwaggerUIStandalonePreset
-    ],
-    plugins: [
-      SwaggerUIBundle.plugins.DownloadUrl
-    ],
-    layout: "StandaloneLayout"
-  })
-
-  window.ui = ui
-}
-</script>
-</body>
-
-</html>

fineract-provider/src/main/resources/swagger-ui/oauth2-redirect.html

@@ -1,53 +0,0 @@
-<!doctype html>
-<html lang="en-US">
-<body onload="run()">
-</body>
-</html>
-<script>
-    'use strict';
-    function run () {
-        var oauth2 = window.opener.swaggerUIRedirectOauth2;
-        var sentState = oauth2.state;
-        var redirectUrl = oauth2.redirectUrl;
-        var isValid, qp, arr;
-
-        qp = (window.location.hash || location.search).substring(1);
-
-        arr = qp.split("&")
-        arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';})
-        qp = qp ? JSON.parse('{' + arr.join() + '}',
-                function (key, value) {
-                    return key === "" ? value : decodeURIComponent(value)
-                }
-        ) : {}
-
-        isValid = qp.state === sentState
-
-        if (oauth2.auth.schema.get("flow") === "accessCode" && !oauth2.auth.code) {
-            if (!isValid) {
-                oauth2.errCb({
-                    authId: oauth2.auth.name,
-                    source: "auth",
-                    level: "warning",
-                    message: "Authorization may be unsafe, passed state was changed in server Passed state wasn't returned from auth server"
-                });
-            }
-
-            if (qp.code) {
-                delete oauth2.state;
-                oauth2.auth.code = qp.code;
-                oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
-            } else {
-                oauth2.errCb({
-                    authId: oauth2.auth.name,
-                    source: "auth",
-                    level: "error",
-                    message: "Authorization failed: no accessCode received from the server"
-                });
-            }
-        } else {
-            oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
-        }
-        window.close();
-    }
-</script>

fineract-provider/src/main/resources/swagger-ui/swagger-ui-bundle.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"swagger-ui-bundle.js","sources":["webpack:///swagger-ui-bundle.js"],"mappings":"AAAA;AAu/FA;AA6+FA;;;;;;;;;;;;;;;;;;;;;;;;;;AA2TA;;;;;;AAoIA;AAi7FA;AAmtCA;AAi0IA;AAioJA;AA2iGA;AAs+FA;AA4kFA;AA6jFA;AAm9CA;AA6jDA;AAgrCA;AA+/EA;;;;;AAu3BA;AA0qJA;;;;;;;;;;;;;;AAwoFA;AA+lIA;AA2hJA;AAo2HA;AA8lGA;AAwiEA;AAo4DA;AAk7DA;AAyHA;;;;;;AA6iGA;AA07FA;;;;;AAi8CA;AAgsFA;AAs2CA;AAilCA;AA+7CA;AA85DA;AA4zCA;AAs5FA;;;;;;;;;AAqlCA;AA2zIA;AAu7FA;AAmrFA;AA20EA","sourceRoot":""}

fineract-provider/src/main/resources/swagger-ui/swagger-ui-standalone-preset.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"swagger-ui-standalone-preset.js","sources":["webpack:///swagger-ui-standalone-preset.js"],"mappings":"AAAA;;;;;AA0SA;AAgyGA;AAuxFA;;;;;;AAocA;AAkvFA;AAu+CA;AAo+CA;AAgrCA;AAuyEA","sourceRoot":""}

fineract-provider/src/main/resources/swagger-ui/swagger-ui.css.map

@@ -1 +0,0 @@
-{"version":3,"file":"swagger-ui.css","sources":[],"mappings":"","sourceRoot":""}

fineract-provider/src/main/resources/swagger-ui/swagger-ui.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"swagger-ui.js","sources":["webpack:///swagger-ui.js"],"mappings":"AAAA;;;;;;AAizCA;AAoyHA;AAmyHA;AAukGA;AA+9BA;AA8jCA;AAyiCA;AAs5BA","sourceRoot":""}