#5

README.md

@@ -6,11 +6,184 @@
 a gradle plugin based on the [openapi-generatr-api][generatr-api] to handle all configured openapi-generatrs
 without explicit dependency on a generatr. Requires Gradle 5.2 or better.
 
-# Usage
+# gradle dsl
 
-See [`Using Gradle`][generatr-spring-gradle] in the documentation of [openapi-generatr-spring][generatr-spring].
+For a more detailed description see [`Using Gradle`][generatr-spring-gradle] in the documentation of
+ [openapi-generatr-spring][generatr-spring].
 
-# Sample project
+The plugin adds a new configuration block `openapiGeneratr` to the gradle project. Each generatr is
+configured by a nested configuration block.
+
+Apart from that there is only a single option that is recognized inside the configuration block:
+
+* `apiPath`, which defines the path to the openapi yaml file. This is usually the same for all
+generatrs and placing it directly into the the `openapiGeneratr` block sets it for all generatrs.
+
+To configure a generatr, for example the [openapi spring generatr][generatr-spring], a `spring`
+configuration is placed into the the `openapiGeneratr` block. The name of the configuration is
+used to create a gradle task `generate<Name>` to run the corresponding generatr.
+
+
+    openapiGeneratr {
+
+        // the path to the open api yaml file.
+        apiPath "${projectDir}/src/api/openapi.yaml"
+
+        spring {
+            ... options of the spring generatr
+        }
+
+    }
+
+
+In case the json generatr is needed it is added in the same way:
+
+
+    openapiGeneratr {
+
+        // the path to the open api yaml file.
+        apiPath "${projectDir}/src/api/openapi.yaml"
+
+        spring {
+            ... options of the spring generatr
+        }
+
+        json {
+            ... options of the json generatr
+        }
+
+    }
+
+
+The configuration of a single generatr has a few pre-defined properties and it can have any number of
+additional parameters defined by the generatr (all options are passed in a map to the generatr with
+ the option name as the key).
+
+* `generatr` (mandatory): the `generatr` dependency. Uses the same dependency notations allowed in the
+gradle `dependencies` block.
+
+    The generatr library is configured here to avoid any side effect on the build dependencies of the
+    project.   
+
+    Example using the preferred shortcut nation:
+
+        spring {
+            generatr 'com.github.hauner.openapi:openapi-generatr-spring:1.0.0.M7'
+        }
+
+  or like this to use an un-published generatr:
+
+        spring {
+            generatr files('... path to generatr jar')
+        }
+
+
+* `apiPath` (optional): the path to the open api yaml file. If set inside a generatr configuration it
+overrides the parent `apiPath`.
+
+* `targetDir` (mandatory): the target folder for the generatr. The generatr will write its output to
+ this directory.
+
+# gradle tasks
+
+The plugin creates a single gradle task for each generatr configuration that will run the corresponding
+generatr. The name is derived from the generatr name:  `generate<Name>`.
+
+
+The plugin does not add the `generate<Name>` task to the build lifecycle. To run it automatically
+add a task dependency in the `build.gradle` file. For example to run generatr-spring before compiling   
+
+    // generate api before compiling
+    compileJava.dependsOn ('generateSpring')
+
+and to run generatr-json when processing the resources:    
+
+    processResources.dependsOn ('generateJson')
+
+
+# using the generatr output 
+
+In case the generatr creates java sources it is necessary to compile them as part of the build process.
+
+For example to compile the java source files created by generatr-spring add the `targetDir` of the 
+generatr to the java `sourceSets`:
+
+    // add the targetDir of the generatr as additional source folder to java.
+    sourceSets {
+        main {
+            java {
+                // add generated files
+                srcDir 'build/openapi'
+            }
+        }
+    }
+
+To add the json file created by the generatr-json to the final artifact jar as resource add the
+`targetDir` of the generatr to the java `resources` source set:
+
+
+    // add the targetDir of the generatr as additional resource folder.
+    sourceSets {
+        main {
+            resources {
+                srcDir "$buildDir/json"
+            }
+        }
+    }
+
+
+# configuration example
+
+Here is a full example using the generatrs [spring][generatr-spring] & [json][generatr-json]:
+
+    openapiGeneratr {
+
+        // the path to the open api yaml file. Usually the same for all generatrs.
+        //
+        apiPath "${projectDir}/src/api/openapi.yaml"
+
+        // based on the name of a generatr configuration the plugin creates a gradle task with name
+        // "generate${name of generator}"  (in this case "generateSpring") to run the generatr.
+        //
+        spring {
+            // the spring generatr dependency (mandatory)
+            //
+            generatr 'com.github.hauner.openapi:openapi-generatr-spring:1.0.0.M7'
+
+            // setting api path inside a generatr configuration override the one at the top.
+            //
+            // apiPath "${projectDir}/src/api/openapi.yaml"
+
+            // the destination folder for generating interfaces & models. This is the parent of the
+            // {package-name} folder tree configured in the mapping file. (mandatory)
+            //
+            targetDir "$projectDir/build/openapi"
+
+            //// generatr-spring specific options
+
+            // file name of the mapping yaml configuration file. Note that the yaml file name must end
+            // with either {@code .yaml} or {@code .yml}.
+            //
+            mapping "$projectDir/openapi-generatr-spring.yaml"
+
+            // show warnings from the open api parser.
+            showWarnings true
+        }
+
+        // applying the rule described above the task to run this one is "generateJson".
+        //
+        json {
+            // the json generatr dependency (mandatory)
+            //
+            generatr 'com.github.hauner.openapi:openapi-generatr-json:1.0.0.M2'
+
+            // the destination folder for the json file. (mandatory)
+            targetDir "$buildDir/json"
+        }
+
+    }
+
+# sample project
 
 See [`openapi-generatr-spring-mvc-sample`][generatr-spring-mvc] for a complete spring boot sample project.
 
@@ -27,5 +200,6 @@ The plugin at the [plugin portal][generatr-plugin].
 
 [generatr-api]: https://github.com/hauner/openapi-generatr-api
 [generatr-spring]: https://github.com/hauner/openapi-generatr-spring
+[generatr-json]: https://github.com/hauner/openapi-generatr-json
 [generatr-spring-mvc]: https://github.com/hauner/openapi-generatr-spring-mvc-sample
 [generatr-spring-gradle]: https://hauner.github.io/openapi-generatr-spring/gradle.html

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 group 'com.github.hauner.openapi'
-version '1.0.0.M4'
+version '1.0.0.M5'
 
 targetCompatibility = JavaVersion.VERSION_1_8
 

src/main/groovy/com/github/hauner/openapi/gradle/Generatr.groovy

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2020 the original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.github.hauner.openapi.gradle
+
+import org.gradle.api.file.FileCollection
+
+/**
+ * represents a generatr configured in {@link OpenApiGeneratrExtension}
+ *
+ * @author Martin Hauner
+ */
+class Generatr {
+    public static final String API_PATH = 'apiPath'
+    public static final String TARGET_DIR = 'targetDir'
+
+    String name
+    def generatrLib  // String | FileCollection...
+
+    Map<String, Object> other = [:]
+
+    Generatr (String name) {
+        this.name = name
+    }
+
+    void generatr (FileCollection fc) {
+        generatrLib = fc
+    }
+
+    void generatr (String dep) {
+        generatrLib = dep
+    }
+
+    void targetDir (String targetDir) {
+        other.put (TARGET_DIR, targetDir)
+    }
+
+    void targetDir (GString targetDir) {
+        other.put (TARGET_DIR, targetDir.toString ())
+    }
+
+    String getTargetDir () {
+        other.get (TARGET_DIR)
+    }
+
+    void apiPath (String apiPath) {
+        other.put (API_PATH, apiPath)
+    }
+
+    void apiPath (GString apiPath) {
+        other.put (API_PATH, apiPath.toString ())
+    }
+
+    boolean hasApiPath () {
+        other.containsKey (API_PATH)
+    }
+
+    String getApiPath () {
+        other.get (API_PATH)
+    }
+
+    void setApiPath (String path) {
+        other.put (API_PATH, path)
+    }
+
+    def methodMissing (String name, def args) {
+        if (args[0] instanceof Closure) {
+            def builder = new MapBuilder()
+            builder.with (args[0] as Closure)
+            other.put (name, builder.get ())
+        } else {
+            other.put (name, args[0])
+        }
+    }
+
+}

src/main/groovy/com/github/hauner/openapi/gradle/MapBuilder.groovy

@@ -85,7 +85,8 @@ class MapBuilder {
     @Override
     void setProperty(String propertyName, Object value) {
         if (props.containsKey (propertyName)) {
-            log.warn ("replacing property {} with value {} to value {}!", propertyName, props.get (propertyName), value)
+            log.warn ("replacing property {} with value {} to value {}!",
+                propertyName, props.get (propertyName), value)
         }
 
         props.put (propertyName, value)