[plugins] new generate client Gradle task and Maven mojo (#688)

Introduces new functionality to generate GraphQL Kotlin client based on the specified queries.

NOTE: This is a final PR in a series to break down #595 into smaller more manageable pieces

Author: dariuszkuc

README.md

@@ -9,10 +9,12 @@ GraphQL Kotlin is a collection of libraries built on top of [graphql-java](https
 
 ## 📦 Modules
 
-* [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) - Code only GraphQL schema generation for Kotlin
+* [graphql-kotlin-client](/graphql-kotlin-client) - Lightweight GraphQL Kotlin HTTP client
 * [graphql-kotlin-federation](/graphql-kotlin-federation) - Schema generator extension to build federated GraphQL schemas
+* [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) - Code only GraphQL schema generation for Kotlin
 * [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) - Spring Boot auto-configuration library to create a GraphQL web app
 * [examples](/examples) - Example apps that use graphql-kotlin libraries to test and demonstrate usages
+* [plugins](/plugins) - GraphQL Kotlin Gradle and Maven plugins
 
 ## ⌨️ Usage
 

docs/getting-started.md

@@ -7,14 +7,18 @@ GraphQL Kotlin is a collection of libraries built on top of [graphql-java](https
 
 ## Modules
 
-* [graphql-kotlin-schema-generator](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-schema-generator)  ([Javadoc](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator))
+* [graphql-kotlin-client](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-client) ([Javadoc](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client))
+  — Lightweight GraphQL Kotlin HTTP client
+* [graphql-kotlin-schema-generator](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-schema-generator) ([Javadoc](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator))
   — Code only GraphQL schema generation for Kotlin
 * [graphql-kotlin-federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-federation) ([Javadoc](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-federation))
   — Schema generator extension to build federated GraphQL schemas
 * [graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server) ([Javadoc](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-spring-server))
   — Spring Boot auto-configuration library to create GraphQL web app
 * [examples](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples)
   — Example apps that use graphql-kotlin libraries to test and demonstrate usages
+* [plugins](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/plugins)
+  — GraphQL Kotlin Gradle and Maven plugins
 
 If you encounter any problems using this library please open up a new
 [Issue](https://github.com/ExpediaGroup/graphql-kotlin/issues)

docs/plugins/gradle-plugin.md

@@ -17,9 +17,32 @@ plugins {
 }
 ```
 
+## Extension
+
 GraphQL Kotlin Gradle Plugin uses an extension on the project named `graphql` of type
-[GraphQLPluginExtension`](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/plugins/graphql-kotlin-gradle-plugin/src/main/kotlin/com/expediagroup/graphql/plugin/gradle/GraphQLPluginExtension.kt).
-This extension can be used to configure global options instead of explicitly configuring individual tasks.
+[GraphQLPluginExtension](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/plugins/graphql-kotlin-gradle-plugin/src/main/kotlin/com/expediagroup/graphql/plugin/gradle/GraphQLPluginExtension.kt).
+This extension can be used to configure global options instead of explicitly configuring individual tasks. Once extension
+is configured, it will automatically download SDL/run introspection to generate GraphQL schema and subsequently generate
+all GraphQL clients. GraphQL Extension should be used by default, except for cases where you need to only run individual
+tasks.
+
+```kotlin
+// build.gradle.kts
+import com.expediagroup.graphql.plugin.gradle.graphql
+
+graphql {
+  // GraphQL server endpoint that will be used to for running introspection queries. Alternatively you can download schema directly from `sdlEndpoint`.
+  endpoint = "http://localhost:8080/graphql"
+  // GraphQL server SDL endpoint that will be used to download schema. Alternatively you can run introspection query against `endpoint`.
+  sdlEndpoint = "http://localhost:8080/sdl"
+  // Target package name to be used for generated classes.
+  packageName = "com.example.generated"
+  // Boolean flag indicating whether or not selection of deprecated fields is allowed.
+  allowDeprecatedFields = false
+  // Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
+  scalarConverters.put("UUID", ScalarConverterMapping("java.util.UUID", "com.example.UUIDScalarConverter"))
+}
+```
 
 ## Tasks
 
@@ -33,13 +56,45 @@ schema file as `schema.graphql` under build directory. In general, this task pro
 and could be used as an alternative to `graphqlIntrospectSchema` to generate input for the subsequent
 `graphqlGenerateClient` task.
 
+**Properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `endpoint` | String | yes | Target GraphQL server SDL endpoint that will be used to download schema.<br/>**Command line property is**: `endpoint`. |
+
+### graphqlGenerateClient
+
+Task that generates GraphQL Kotlin client and corresponding data classes based on the provided GraphQL queries that are
+evaluated against target Graphql schema. Individual clients with their specific data models are generated for each query
+file and are placed under specified `packageName`.
+
+**Properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `allowDeprecatedFields` | Boolean | | Boolean flag indicating whether selection of deprecated fields is allowed or not.<br/>**Default value is:** `false`.<br/>**Command line property is**: `allowDeprecatedFields`. |
+| `packageName` | String | yes | Target package name for generated code.<br/>**Command line property is**: `packageName`. |
+| `queryFiles` | FileCollection | | List of query files to be processed. Instead of a list of files to be processed you can specify `queryFileDirectory` directory instead. If this property is specified it will take precedence over the corresponding directory property. |
+| `queryFileDirectory` | String | | Directory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.<br/>**Default value is:** `src/main/resources`.<br/>**Command line property is**: `queryFileDirectory`. |
+| `scalarConverters` | Map<String, ScalarConverter> | | Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values. |
+| `schemaFile` | File | `schemaFileName` or `schemaFile` has to be provided | GraphQL schema file that will be used to generate client code. |
+| `schemaFileName` | String | `schemaFileName` or `schemaFile` has to be provided | Path to GraphQL schema file that will be used to generate client code.<br/>**Command line property is**: `schemaFileName`. |
+
 ### graphqlIntrospectSchema
 
-Executes GraphQL introspection query against specified endpoint and saves the underlying schema file as
+Task that executes GraphQL introspection query against specified `endpoint` and saves the underlying schema file as
 `schema.graphql` under build directory. In general, this task provides limited functionality by itself and instead
 should be used to generate input for the subsequent `graphqlGenerateClient` task.
 
-## Downloading Schema SDL
+**Properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `endpoint` | String | yes | Target GraphQL server endpoint that will be used to execute introspection queries.<br/>**Command line property is**: `endpoint`. |
+
+## Examples
+
+### Downloading Schema SDL
 
 GraphQL endpoints are often public and as such many servers might disable introspection queries in production environment.
 Since GraphQL schema is needed to generate type safe clients, as alternative GraphQL servers might expose private
@@ -51,65 +106,136 @@ be executed directly from the command line by explicitly passing `endpoint` para
 $ gradle graphqlDownloadSDL --endpoint="http://localhost:8080/sdl"
 ```
 
-Task can also be configured in your Gradle build file using global extension
+Task can also be explicitly configured in your Gradle build file
 
 ```kotlin
 // build.gradle.kts
-import com.expediagroup.graphql.plugin.gradle.graphql
+import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLDownloadSDLTask
 
-graphql {
-  sdlEndpoint = "http://localhost:8080/graphql"
+val graphqlIntrospectSchema by tasks.getting(GraphQLDownloadSDLTask::class) {
+    graphqlDownloadSDL.set("http://localhost:8080/sdl")
 }
 ```
 
-Or by explicitly configuring the task
+NOTE: This task does not automatically configure itself to be part of your build lifecycle. You will need to explicitly
+invoke it OR configure it as a dependency of some other task.
+
+### Introspecting Schema
+
+Introspection task requires target GraphQL server `endpoint` to be specified. Task can be executed directly from the
+command line by explicitly passing endpoint parameter
+
+```shell script
+$ gradle graphqlIntrospectSchema --endpoint="http://localhost:8080/graphql"
+```
+
+Task can also be explicitly configured in your Gradle build file
 
 ```kotlin
 // build.gradle.kts
-import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLDownloadSDLTask
+import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask
 
-val graphqlIntrospectSchema by tasks.getting(GraphQLDownloadSDLTask::class) {
-    graphqlDownloadSDL.set("http://localhost:8080/graphql")
+val graphqlIntrospectSchema by tasks.getting(GraphQLIntrospectSchemaTask::class) {
+    endpoint.set("http://localhost:8080/graphql")
 }
 ```
 
 NOTE: This task does not automatically configure itself to be part of your build lifecycle. You will need to explicitly
 invoke it OR configure it as a dependency of some other task.
 
-## Introspecting Schema
+### Generating Client
 
-Introspection task requires target GraphQL server `endpoint` to be specified. Task can be executed directly from the
-command line by explicitly passing endpoint parameter
+GraphQL client code is generated based on the provided queries that will be executed against target GraphQL `schemaFile`.
+Separate class is generated for each provided GraphQL query and are saved under specified `packageName`. When using default
+configuration and storing GraphQL queries under `src/main/resources` directories, task can be executed directly from the
+command line by explicitly providing required properties.
 
 ```shell script
-$ gradle graphqlIntrospectSchema --endpoint="http://localhost:8080/graphql"
+$ gradle graphqlGenerateClient --schemaFileName"mySchema.graphql" --packageName="com.example.generated"
 ```
 
-Task can also be configured in your Gradle build file using global extension
+Task can also be explicitly configured in your Gradle build file
 
 ```kotlin
 // build.gradle.kts
-import com.expediagroup.graphql.plugin.gradle.graphql
+import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask
 
-graphql {
-  endpoint = "http://localhost:8080/graphql"
+val graphqlGenerateClient by tasks.getting(GraphQLGenerateClientTask::class) {
+  packageName.set("com.example.generated")
+  schemaFileName.set("mySchema.graphql")
+}
+```
+
+This will process all GraphQL queries located under `src/main/resources` and generate corresponding GraphQL Kotlin clients.
+Generated classes will be automatically added to the project compile sources.
+
+### Generating client with Custom Scalars
+
+By default, all custom GraphQL scalars will be serialized as Strings. You can override this default behavior by specifying
+custom [scalar converter](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-client/src/main/kotlin/com/expediagroup/graphql/client/converter/ScalarConverter.kt).
+
+For example given following custom scalar in our GraphQL schema
+
+```graphql
+scalar UUID
+```
+
+We can create a custom converter to automatically convert this custom scalar to `java.util.UUID`
+
+```kotlin
+package com.example
+
+import com.expediagroup.graphql.client.converter.ScalarConverter
+import java.util.UUID
+
+class UUIDScalarConverter : ScalarConverter<UUID> {
+    override fun toScalar(rawValue: String): UUID = UUID.fromString(rawValue)
+    override fun toJson(value: UUID): String = value.toString()
 }
 ```
 
-Or by explicitly configuring the task
+Afterwards we need to configure our plugin to use this custom converter
 
 ```kotlin
 // build.gradle.kts
 import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask
 
-val graphqlIntrospectSchema by tasks.getting(GraphQLIntrospectSchemaTask::class) {
-    endpoint.set("http://localhost:8080/graphql")
+val graphqlGenerateClient by tasks.getting(GraphQLGenerateClientTask::class) {
+  packageName.set("com.example.generated")
+  schemaFileName.set("mySchema.graphql")
+  scalarConverters.put("UUID", ScalarConverterMapping("java.util.UUID", "com.example.UUIDScalarConverter"))
 }
 ```
 
-NOTE: This task does not automatically configure itself to be part of your build lifecycle. You will need to explicitly
-invoke it OR configure it as a dependency of some other task.
+### Complete Configuration Example
+
+Following is the minimal configuration that runs introspection query against a target GraphQL server and generates a
+corresponding schema. This generated schema is subsequently used to generate GraphQL client code based on the queries
+provided under `src/main/resources` directory.
+
+```kotlin
+// build.gradle.kts
+import com.expediagroup.graphql.plugin.gradle.graphql
+
+graphql {
+    endpoint = "http://localhost:8080/graphql"
+    packageName = "com.example.generated"
+}
+```
+
+Above configuration is equivalent to the following
 
-## Complete Example
+```kotlin
+// build.gradle.kts
+import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask
+import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLIntrospectSchemaTask
 
-// TODO complete once all tasks are merged
+val graphqlIntrospectSchema by tasks.getting(GraphQLIntrospectSchemaTask::class) {
+  endpoint.set("http://localhost:8080/graphql")
+}
+val graphqlGenerateClient by tasks.getting(GraphQLGenerateClientTask::class) {
+  packageName.set("com.example.generated")
+  schemaFile.set(graphqlIntrospectSchema.outputFile)
+  dependsOn("graphqlIntrospectSchema")
+}
+```