Merge pull request #4 from kpramesh2212/master

Feat: Add readme file and an initial working plugin

Author: bnasslahsen

README.md

@@ -1,3 +1,91 @@
+#**Introduction to springdoc-openapi-gradle-plugin**
+Spring Docs Open API Gradle Plugin - Generates OpenAPI-3 specification docs for spring boot application
 
+This Gradle plugin provides the capability to generate OpenAPI-3 specification docs for spring boot application from a Gradle build. 
+The plugin does this with help of springdoc-openapi-core
 
-## **Introduction to springdoc-openapi-gradle-plugin**
+Compatibility Notes
+-------------------
+
+The plugin is build on gradle version 6.1. 
+
+Dependencies
+------------
+This plugin has a runtime dependency on the the following plugins
+
+1. Spring boot gradle plugin - "org.springframework.boot"
+2. Gradle process plugin - "com.github.johnrengelman.processes"
+
+Hence these plugins also needs to be added to your gradle builds.
+
+Note: You will also need the springdocs-core jar file to be present in your spring boot application
+
+How To Use
+----------
+
+Gradle Groovy DSL
+
+```groovy
+plugins {
+      id("org.springframework.boot") version "2.2.4.RELEASE"
+      id "com.github.johnrengelman.processes" version "0.5.0"
+      id("org.springdoc.openapi-gradle-plugin") version "1.0-SNAPSHOT"
+}
+```
+
+Gradle Kotlin DSL
+```groovy
+plugins {
+    id("org.springframework.boot") version "2.2.4.RELEASE"
+    id("com.github.johnrengelman.processes") version "0.5.0"
+    id("org.springdoc.openapi-gradle-plugin") version "1.0-SNAPSHOT"
+}
+```
+
+Note: For latest versions of the plugins please check the gradle plugin portal
+
+How the plugin works
+------------
+
+When the user add this plugin and its runtime dependency plugins to your build file 
+
+The plugin creates the following tasks
+
+1. forkedSpringBootRun
+
+2. generateOpenApiDocs
+
+Running the task generateOpenApiDocs will generate the open api docs into a file openapi.json in your projects build dir
+
+```bash
+gradle clean generateOpenApiDocs
+``` 
+
+When you run the gradle task **generateOpenApiDocs**, it starts your spring boot application in the background using **forkedSpringBootRun** task.
+Once your application is up and running **generateOpenApiDocs** makes a rest call to your applications doc url to download and store the open api docs file as json. 
+
+
+Customization
+-------------
+
+The following customizations can be done on task generateOpenApiDocs using extension openApi as follows
+
+```kotlin
+openApi {
+    apiDocsUrl.set("https://localhost:9000/api/docs")
+    outputDir.set(file("$buildDir/docs"))
+    outputFileName.set("swagger.json")
+    waitTimeInSeconds.set(10)
+}
+```
+
+Parameter | Description | Required | Default
+--------- | ----------- | -------- | -------
+`apiDocsUrl` |  The url from where the open api docs can be downloaded | No | http://localhost:8080/v3/api-docs
+`outputDir` | The output directory where the generated open api file would be placed | No | $buildDir - Your projects build dir
+`outputFileName` | The name of the output file with extension | No | openapi.json
+`waitTimeInSeconds` | Time to wait in seconds for your spring boot application to start, before we make calls to `apiDocsUrl` to download the openapi docs | No | 10 seconds
+
+# Building the plugin
+
+TODO

build.gradle.kts

@@ -13,6 +13,7 @@ repositories {
         name = "Spring Repositories"
         url = uri("https://repo.spring.io/libs-release/")
     }
+    gradlePluginPortal()
 }
 
 publishing {
@@ -31,6 +32,8 @@ dependencies {
     implementation(kotlin("reflect"))
     implementation(group = "khttp", name = "khttp", version = "1.0.0")
     implementation(group = "com.google.code.gson", name = "gson", version = "2.8.6")
+    implementation(group = "com.jayway.awaitility", name = "awaitility", version = "1.7.0")
+    implementation(files("/home/ramesh/gradle-processes/build/libs/gradle-processes-0.5.0.jar"))
 }
 
 gradlePlugin {

gradle/wrapper/gradle-wrapper.jar

@@ -1,6 +1,15 @@
 package org.springdoc.openapi.gradle.plugin
 
-const val TASK_NAME = "generateOpenApiFile"
 const val EXTENSION_NAME = "openApi"
 const val GROUP_NAME = "OpenApi"
-const val OPENAPI_TASK_DESCRIPTION = "Generates the spring doc openapi file"
+const val OPEN__API_TASK_NAME = "generateOpenApiDocs"
+const val OPEN_API_TASK_DESCRIPTION = "Generates the spring doc openapi file"
+const val SPRING_BOOT_JAR_TASK_NAME = "bootJar"
+const val FORKED_SPRING_BOOT_RUN_TASK_NAME = "forkedSpringBootRun"
+
+const val DEFAULT_API_DOCS_URL = "http://localhost:8080/v3/api-docs"
+const val DEFAULT_OPEN_API_FILE_NAME = "openapi.json"
+const val DEFAULT_WAIT_TIME_IN_SECONDS = 10
+
+const val SPRING_BOOT_PLUGIN = "org.springframework.boot"
+const val PROCESS_PLUGIN = "com.github.johnrengelman.processes"

gradle/wrapper/gradle-wrapper.properties

@@ -9,4 +9,5 @@ open class OpenApiExtension @Inject constructor(project: Project) {
     val apiDocsUrl: Property<String> = project.objects.property(String::class.java)
     val outputFileName: Property<String> = project.objects.property(String::class.java)
     val outputDir: DirectoryProperty = project.objects.directoryProperty()
+    val waitTimeInSeconds: Property<Int> = project.objects.property(Int::class.java)
 }

src/main/kotlin/org/springdoc/openapi/gradle/plugin/Constants.kt

@@ -2,6 +2,8 @@ package org.springdoc.openapi.gradle.plugin
 
 import com.google.gson.GsonBuilder
 import com.google.gson.JsonObject
+import com.jayway.awaitility.core.ConditionTimeoutException
+import khttp.responses.Response
 import org.gradle.api.DefaultTask
 import org.gradle.api.GradleException
 import org.gradle.api.file.DirectoryProperty
@@ -19,34 +21,41 @@ open class OpenApiGeneratorTask: DefaultTask() {
     val outputFileName: Property<String> = project.objects.property(String::class.java)
     @get:OutputDirectory
     val outputDir: DirectoryProperty = project.objects.directoryProperty()
+    private val waitTimeInSeconds: Property<Int> = project.objects.property(Int::class.java)
 
     init {
-        description = OPENAPI_TASK_DESCRIPTION
+        description = OPEN_API_TASK_DESCRIPTION
         group = GROUP_NAME
-
-        val defaultOutputDir = project.objects.directoryProperty()
-        defaultOutputDir.set(project.buildDir)
+        // load my extensions
         val extension: OpenApiExtension = project.extensions.run {
             getByName(EXTENSION_NAME) as OpenApiExtension
         }
 
-        apiDocsUrl.set(extension.apiDocsUrl.getOrElse("http://localhost:8080/v3/api-docs"))
-        outputFileName.set(extension.outputFileName.getOrElse("openapi.json"))
+        // set a default value if not provided
+        val defaultOutputDir = project.objects.directoryProperty()
+        defaultOutputDir.set(project.buildDir)
+
+        apiDocsUrl.set(extension.apiDocsUrl.getOrElse(DEFAULT_API_DOCS_URL))
+        outputFileName.set(extension.outputFileName.getOrElse(DEFAULT_OPEN_API_FILE_NAME))
         outputDir.set(extension.outputDir.getOrElse(defaultOutputDir.get()))
+        waitTimeInSeconds.set(extension.waitTimeInSeconds.getOrElse(DEFAULT_WAIT_TIME_IN_SECONDS))
     }
 
     @TaskAction
     fun execute() {
-        val response = khttp.get(apiDocsUrl.get())
-        if (response.statusCode > 299) {
-            LOGGER.error("Invalid response code {} while connecting to {}", response.statusCode, apiDocsUrl.get())
-            throw GradleException("Unable to connect to apiDocsUrl ${apiDocsUrl.get()}")
+        try {
+            // I need to change this later on to use a smart logic to wait only for required time
+            Thread.sleep(waitTimeInSeconds.get().toLong() * 1000)
+            val response: Response = khttp.get(apiDocsUrl.get())
+            val gson = GsonBuilder().setPrettyPrinting().create();
+            val googleJsonObject = gson.fromJson(response.jsonObject.toString(), JsonObject::class.java)
+
+            val outputFile = outputDir.file(outputFileName.get()).get().asFile
+            outputFile.writeText(gson.toJson(googleJsonObject))
+        } catch (e: ConditionTimeoutException) {
+            LOGGER.error("Unable to connect to ${apiDocsUrl.get()} waited for ${waitTimeInSeconds.get()} seconds")
+            throw GradleException("Timeout occurred while trying to connect to ${apiDocsUrl.get()}")
         }
-        val gson = GsonBuilder().setPrettyPrinting().create();
-        val googleJsonObject = gson.fromJson(response.jsonObject.toString(), JsonObject::class.java)
-
-        val outputFile = outputDir.file(outputFileName.get()).get().asFile
-        outputFile.writeText(gson.toJson(googleJsonObject))
     }
 
 }

src/main/kotlin/org/springdoc/openapi/gradle/plugin/OpenApiExtension.kt

@@ -1,11 +1,43 @@
 package org.springdoc.openapi.gradle.plugin
 
+import com.github.jengelman.gradle.plugins.processes.tasks.Fork
 import org.gradle.api.Plugin
 import org.gradle.api.Project
+import org.slf4j.LoggerFactory
 
 open class OpenApiGradlePlugin: Plugin<Project> {
+    private val LOGGER = LoggerFactory.getLogger(OpenApiGradlePlugin::class.java)
+
     override fun apply(project: Project) {
+        // Run time dependency on the following plugins
+        project.plugins.apply(SPRING_BOOT_PLUGIN)
+        project.plugins.apply(PROCESS_PLUGIN)
+
         project.extensions.create(EXTENSION_NAME, OpenApiExtension::class.java, project)
-        project.tasks.register(TASK_NAME, OpenApiGeneratorTask::class.java)
+
+        project.afterEvaluate {
+            // Spring boot jar task
+            val bootJarTask = project.tasks.named(SPRING_BOOT_JAR_TASK_NAME)
+
+            // Create a forked version spring boot run task
+            val forkedSpringBoot = project.tasks.register(FORKED_SPRING_BOOT_RUN_TASK_NAME, Fork::class.java) { fork ->
+                fork.dependsOn(bootJarTask)
+
+                fork.onlyIf {
+                    val bootJar = bootJarTask.get().outputs.files.first()
+                    fork.commandLine = listOf("java", "-jar", "$bootJar")
+                    true
+                }
+            }
+
+            // This is my task. Before I can run it I have to run the dependent tasks
+            val openApiGeneratorTask  = project.tasks.register(OPEN__API_TASK_NAME, OpenApiGeneratorTask::class.java) {
+                it.dependsOn(forkedSpringBoot)
+                it.doLast {
+                    forkedSpringBoot.get().processHandle.abort()
+                }
+            }
+        }
+
     }
 }