[plugin] update client generator to support kotlinx serialization (#1069)

This is a second PR in a series to introduce support for both `Jackson` and `kotlinx.serialization` data formats for GraphQL Kotlin clients.

This PR updates `graphql-kotlin-client-generator` to allow generating data models supporting both formats. Due to the declaration limitations of Kotlin sealed classes (in Kotlin 1.4 sealed classes and their implementations have to be a top level definitions), generation logic was also updated to generate operation specific data models under package name matching that operation name. Common objects such as input objects, enums and custom scalars definitions will be shared across different queries.

Large size of PR is driven primarily with test cases - instead of comparing generated classes against a hard coded Strings, tests were updated to compare it against files. Generator tests were also updated to verify generated sources can be compiled.

* #1048 - this is an attempt to split it up to more manageable pieces
* #929 - add support for generating `kotlinx.serialization` data models
* #1066 - first PR in the series

Author: dariuszkuc

examples/client/gradle-client/build.gradle.kts

@@ -1,4 +1,3 @@
-import com.expediagroup.graphql.plugin.gradle.config.GraphQLClientType
 import com.expediagroup.graphql.plugin.gradle.config.GraphQLScalar
 import com.expediagroup.graphql.plugin.gradle.graphql
 
@@ -31,7 +30,6 @@ graphql {
         allowDeprecatedFields = true
         headers = mapOf("X-Custom-Header" to "My-Custom-Header")
         customScalars = listOf(GraphQLScalar("UUID", "java.util.UUID", "com.expediagroup.graphql.examples.client.gradle.UUIDScalarConverter"))
-        clientType = GraphQLClientType.KTOR
     }
 }
 ktlint {

examples/client/gradle-client/src/main/kotlin/com/expediagroup/graphql/examples/client/gradle/Application.kt

@@ -22,6 +22,8 @@ import com.expediagroup.graphql.generated.ExampleQuery
 import com.expediagroup.graphql.generated.HelloWorldQuery
 import com.expediagroup.graphql.generated.RetrieveObjectQuery
 import com.expediagroup.graphql.generated.UpdateObjectMutation
+import com.expediagroup.graphql.generated.inputs.BasicObjectInput
+import com.expediagroup.graphql.generated.inputs.SimpleArgumentInput
 import io.ktor.client.HttpClient
 import io.ktor.client.engine.okhttp.OkHttp
 import io.ktor.client.features.logging.DEFAULT
@@ -71,16 +73,16 @@ fun main() {
         val retrieveNonExistentObject = client.execute(RetrieveObjectQuery(variables = RetrieveObjectQuery.Variables(id = 1)))
         println("\tretrieve non existent object: ${retrieveNonExistentObject.data?.retrieveBasicObject}")
 
-        val addResult = client.execute(AddObjectMutation(variables = AddObjectMutation.Variables(newObject = AddObjectMutation.BasicObjectInput(1, "first"))))
+        val addResult = client.execute(AddObjectMutation(variables = AddObjectMutation.Variables(newObject = BasicObjectInput(1, "first"))))
         println("\tadd new object: ${addResult.data?.addBasicObject}")
 
-        val updateResult = client.execute(UpdateObjectMutation(variables = UpdateObjectMutation.Variables(updatedObject = UpdateObjectMutation.BasicObjectInput(1, "updated"))))
+        val updateResult = client.execute(UpdateObjectMutation(variables = UpdateObjectMutation.Variables(updatedObject = BasicObjectInput(1, "updated"))))
         println("\tupdate new object: ${updateResult.data?.updateBasicObject}")
     }
 
     println("additional examples")
     runBlocking {
-        val exampleData = client.execute(ExampleQuery(variables = ExampleQuery.Variables(simpleCriteria = ExampleQuery.SimpleArgumentInput(max = 1.0f))))
+        val exampleData = client.execute(ExampleQuery(variables = ExampleQuery.Variables(simpleCriteria = SimpleArgumentInput(max = 1.0f))))
         println("\tretrieved interface: ${exampleData.data?.interfaceQuery} ")
         println("\tretrieved union: ${exampleData.data?.unionQuery} ")
         println("\tretrieved enum: ${exampleData.data?.enumQuery} ")

examples/client/maven-client/src/main/kotlin/com/expediagroup/graphql/examples/client/maven/Application.kt

@@ -22,6 +22,8 @@ import com.expediagroup.graphql.generated.ExampleQuery
 import com.expediagroup.graphql.generated.HelloWorldQuery
 import com.expediagroup.graphql.generated.RetrieveObjectQuery
 import com.expediagroup.graphql.generated.UpdateObjectMutation
+import com.expediagroup.graphql.generated.inputs.BasicObjectInput
+import com.expediagroup.graphql.generated.inputs.SimpleArgumentInput
 import io.netty.channel.ChannelOption
 import kotlinx.coroutines.runBlocking
 import org.springframework.http.client.reactive.ClientHttpConnector
@@ -64,16 +66,16 @@ fun main() {
         val retrieveNonExistentObject = client.execute(RetrieveObjectQuery(variables = RetrieveObjectQuery.Variables(id = 1)))
         println("\tretrieve non existent object: ${retrieveNonExistentObject.data?.retrieveBasicObject}")
 
-        val addResult = client.execute(AddObjectMutation(variables = AddObjectMutation.Variables(newObject = AddObjectMutation.BasicObjectInput(1, "first"))))
+        val addResult = client.execute(AddObjectMutation(variables = AddObjectMutation.Variables(newObject = BasicObjectInput(1, "first"))))
         println("\tadd new object: ${addResult.data?.addBasicObject}")
 
-        val updateResult = client.execute(UpdateObjectMutation(variables = UpdateObjectMutation.Variables(updatedObject = UpdateObjectMutation.BasicObjectInput(1, "updated"))))
+        val updateResult = client.execute(UpdateObjectMutation(variables = UpdateObjectMutation.Variables(updatedObject = BasicObjectInput(1, "updated"))))
         println("\tupdate new object: ${updateResult.data?.updateBasicObject}")
     }
 
     println("additional examples")
     runBlocking {
-        val exampleData = client.execute(ExampleQuery(variables = ExampleQuery.Variables(simpleCriteria = ExampleQuery.SimpleArgumentInput(max = 1.0f))))
+        val exampleData = client.execute(ExampleQuery(variables = ExampleQuery.Variables(simpleCriteria = SimpleArgumentInput(max = 1.0f))))
         println("\tretrieved interface: ${exampleData.data?.interfaceQuery} ")
         println("\tretrieved union: ${exampleData.data?.unionQuery} ")
         println("\tretrieved enum: ${exampleData.data?.enumQuery} ")

plugins/client/graphql-kotlin-client-generator/README.md

@@ -27,6 +27,5 @@ using [square/kotlinpoet](https://github.com/square/kotlinpoet) library.
 
 ## Code Generation Limitations
 
-* Due to the custom logic required for deserialization of polymorphic types and default enum values only Jackson is currently supported.
 * Only a single operation per GraphQL query file is supported.
 * Subscriptions are currently NOT supported.

plugins/client/graphql-kotlin-client-generator/build.gradle.kts

@@ -1,24 +1,25 @@
 description = "GraphQL Kotlin common utilities to generate a client."
 
+val compileTestingVersion: String by project
 val graphQLJavaVersion: String by project
+val junitVersion: String by project
 val kotlinPoetVersion: String by project
+val kotlinxSerializationVersion: String by project
 val ktorVersion: String by project
 val wireMockVersion: String by project
 
 dependencies {
-    api(project(path = ":graphql-kotlin-ktor-client"))
-    api(project(path = ":graphql-kotlin-spring-client")) {
-        exclude(group = "org.jetbrains.kotlinx", module = "kotlinx-coroutines-reactor")
-        exclude(group = "org.springframework")
-        exclude(group = "org.springframework.boot")
-    }
+    api(project(path = ":graphql-kotlin-client"))
     api("com.graphql-java:graphql-java:$graphQLJavaVersion") {
         exclude(group = "com.graphql-java", module = "java-dataloader")
     }
     api("com.squareup:kotlinpoet:$kotlinPoetVersion")
+    api("org.jetbrains.kotlinx:kotlinx-serialization-json:$kotlinxSerializationVersion")
     implementation("io.ktor:ktor-client-cio:$ktorVersion")
     implementation("io.ktor:ktor-client-jackson:$ktorVersion")
     testImplementation("com.github.tomakehurst:wiremock-jre8:$wireMockVersion")
+    testImplementation("com.github.tschuchortdev:kotlin-compile-testing:$compileTestingVersion")
+    testImplementation("org.junit.jupiter:junit-jupiter-params:$junitVersion")
 }
 
 tasks {

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/downloadSchema.kt

@@ -23,14 +23,12 @@ import io.ktor.client.engine.cio.endpoint
 import io.ktor.client.features.ClientRequestException
 import io.ktor.client.request.get
 import io.ktor.client.request.header
-import io.ktor.util.KtorExperimentalAPI
 import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.runBlocking
 
 /**
  * Downloads GraphQL SDL from the specified endpoint and verifies whether the result is a valid GraphQL schema.
  */
-@KtorExperimentalAPI
 fun downloadSchema(
     endpoint: String,
     httpHeaders: Map<String, Any> = emptyMap(),

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generateClient.kt

@@ -18,7 +18,7 @@ package com.expediagroup.graphql.plugin.client
 
 import com.expediagroup.graphql.plugin.client.generator.GraphQLClientGenerator
 import com.expediagroup.graphql.plugin.client.generator.GraphQLClientGeneratorConfig
-import com.expediagroup.graphql.plugin.client.generator.GraphQLClientType
+import com.expediagroup.graphql.plugin.client.generator.GraphQLSerializer
 import com.expediagroup.graphql.plugin.client.generator.GraphQLScalar
 import com.squareup.kotlinpoet.FileSpec
 import graphql.schema.idl.SchemaParser
@@ -31,7 +31,7 @@ fun generateClient(
     packageName: String,
     allowDeprecated: Boolean = false,
     customScalarsMap: List<GraphQLScalar> = emptyList(),
-    clientType: GraphQLClientType = GraphQLClientType.DEFAULT,
+    serializer: GraphQLSerializer = GraphQLSerializer.JACKSON,
     schema: File,
     queries: List<File>
 ): List<FileSpec> {
@@ -40,7 +40,7 @@ fun generateClient(
         packageName = packageName,
         allowDeprecated = allowDeprecated,
         customScalarMap = customScalars,
-        clientType = clientType
+        serializer = serializer
     )
     val graphQLSchema = SchemaParser().parse(schema)
     val generator = GraphQLClientGenerator(graphQLSchema, config)

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generator/GraphQLClientGenerator.kt

@@ -32,6 +32,7 @@ import graphql.language.ObjectTypeDefinition
 import graphql.language.OperationDefinition
 import graphql.parser.Parser
 import graphql.schema.idl.TypeDefinitionRegistry
+import kotlinx.serialization.Serializable
 import java.io.File
 
 private const val CORE_TYPES_PACKAGE = "com.expediagroup.graphql.client.types"
@@ -45,14 +46,23 @@ class GraphQLClientGenerator(
 ) {
     private val documentParser: Parser = Parser()
     private val typeAliases: MutableMap<String, TypeAliasSpec> = mutableMapOf()
+    private val sharedTypes: MutableMap<ClassName, List<TypeSpec>> = mutableMapOf()
 
     /**
      * Generate GraphQL clients for the specified queries.
      */
     fun generate(queries: List<File>): List<FileSpec> {
         val result = mutableListOf<FileSpec>()
         for (query in queries) {
-            result.add(generate(query))
+            result.addAll(generate(query))
+        }
+
+        for ((className, typeSpecs) in sharedTypes) {
+            val fileSpec = FileSpec.builder(className.packageName, className.simpleName)
+            for (type in typeSpecs) {
+                fileSpec.addType(type)
+            }
+            result.add(fileSpec.build())
         }
         if (typeAliases.isNotEmpty()) {
             val typeAliasSpec = FileSpec.builder(packageName = config.packageName, fileName = "GraphQLTypeAliases")
@@ -67,7 +77,7 @@ class GraphQLClientGenerator(
     /**
      * Generate GraphQL client wrapper class and data classes that match the specified query.
      */
-    internal fun generate(queryFile: File): FileSpec {
+    internal fun generate(queryFile: File): List<FileSpec> {
         val queryConst = queryFile.readText().trim()
         val queryDocument = documentParser.parseDocument(queryConst)
 
@@ -76,8 +86,8 @@ class GraphQLClientGenerator(
             throw MultipleOperationsInFileException
         }
 
-        val fileSpec = FileSpec.builder(packageName = config.packageName, fileName = queryFile.nameWithoutExtension.capitalize())
-
+        val fileSpecs = mutableListOf<FileSpec>()
+        val operationFileSpec = FileSpec.builder(packageName = config.packageName, fileName = queryFile.nameWithoutExtension.capitalize())
         operationDefinitions.forEach { operationDefinition ->
             val operationTypeName = operationDefinition.name?.capitalize() ?: queryFile.nameWithoutExtension.capitalize()
             val context = GraphQLClientGeneratorContext(
@@ -86,14 +96,15 @@ class GraphQLClientGenerator(
                 rootType = operationTypeName,
                 queryDocument = queryDocument,
                 allowDeprecated = config.allowDeprecated,
-                customScalarMap = config.customScalarMap
+                customScalarMap = config.customScalarMap,
+                serializer = config.serializer
             )
             val queryConstName = operationTypeName.toUpperUnderscore()
             val queryConstProp = PropertySpec.builder(queryConstName, STRING)
                 .addModifiers(KModifier.CONST)
                 .initializer("%S", queryConst)
                 .build()
-            fileSpec.addProperty(queryConstProp)
+            operationFileSpec.addProperty(queryConstProp)
 
             val rootType = findRootType(operationDefinition)
             val graphQLResponseTypeSpec = generateGraphQLObjectTypeSpec(context, rootType, operationDefinition.selectionSet, "Result")
@@ -106,6 +117,9 @@ class GraphQLClientGenerator(
                 .addSuperinterface(ClassName(CORE_TYPES_PACKAGE, "GraphQLClientRequest").parameterizedBy(kotlinResultTypeName))
                 .addProperty(queryProperty)
 
+            if (config.serializer == GraphQLSerializer.KOTLINX) {
+                operationTypeSpec.addAnnotation(Serializable::class)
+            }
             if (operationDefinition.name != null) {
                 val operationNameProperty = PropertySpec.builder("operationName", STRING, KModifier.OVERRIDE)
                     .initializer("%S", operationDefinition.name)
@@ -137,15 +151,36 @@ class GraphQLClientGenerator(
                     .addStatement("return %T::class", kotlinResultTypeName)
                     .build()
             )
-
-            context.typeSpecs.forEach {
-                operationTypeSpec.addType(it.value)
+            operationTypeSpec.addType(graphQLResponseTypeSpec)
+
+            val polymorphicTypes = mutableListOf<ClassName>()
+            for ((superClassName, implementations) in context.polymorphicTypes) {
+                polymorphicTypes.add(superClassName)
+                val polymorphicTypeSpec = FileSpec.builder(superClassName.packageName, superClassName.simpleName)
+                for (implementation in implementations) {
+                    polymorphicTypes.add(implementation)
+                    context.typeSpecs[implementation]?.let { typeSpec ->
+                        polymorphicTypeSpec.addType(typeSpec)
+                    }
+                }
+                fileSpecs.add(polymorphicTypeSpec.build())
+            }
+            context.typeSpecs.minus(polymorphicTypes).forEach { (className, typeSpec) ->
+                val outputTypeFileSpec = FileSpec.builder(className.packageName, className.simpleName)
+                    .addType(typeSpec)
+                    .build()
+                fileSpecs.add(outputTypeFileSpec)
             }
-            fileSpec.addType(operationTypeSpec.build())
+            operationFileSpec.addType(operationTypeSpec.build())
+            fileSpecs.add(operationFileSpec.build())
 
+            // shared types
+            sharedTypes.putAll(context.enumClassToTypeSpecs.mapValues { listOf(it.value) })
+            sharedTypes.putAll(context.inputClassToTypeSpecs.mapValues { listOf(it.value) })
+            sharedTypes.putAll(context.scalarsClassToTypeSpec)
             typeAliases.putAll(context.typeAliases)
         }
-        return fileSpec.build()
+        return fileSpecs
     }
 
     private fun findRootType(operationDefinition: OperationDefinition): ObjectTypeDefinition {

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generator/GraphQLClientGeneratorConfig.kt

@@ -26,8 +26,8 @@ data class GraphQLClientGeneratorConfig(
     val allowDeprecated: Boolean = false,
     /** Custom scalar type to converter mapping. */
     val customScalarMap: Map<String, GraphQLScalar> = emptyMap(),
-    /** Supported client type to be generated. */
-    val clientType: GraphQLClientType = GraphQLClientType.DEFAULT
+    /** Type of JSON serializer to be used. */
+    val serializer: GraphQLSerializer = GraphQLSerializer.JACKSON
 )
 
 /**
@@ -43,13 +43,9 @@ data class GraphQLScalar(
 )
 
 /**
- * Type of GraphQL HTTP client to generate.
+ * Type of JSON serializer that will be used to generate the data classes.
  */
-enum class GraphQLClientType {
-    /** Generic GraphQL client. */
-    DEFAULT,
-    /** Ktor based GraphQL client. */
-    KTOR,
-    /** Spring WebClient based GraphQL client. */
-    WEBCLIENT
+enum class GraphQLSerializer {
+    KOTLINX,
+    JACKSON
 }

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generator/GraphQLClientGeneratorContext.kt

@@ -33,11 +33,19 @@ data class GraphQLClientGeneratorContext(
     val rootType: String,
     val queryDocument: Document,
     val allowDeprecated: Boolean = false,
-    val customScalarMap: Map<String, GraphQLScalar> = mapOf()
+    val customScalarMap: Map<String, GraphQLScalar> = mapOf(),
+    val serializer: GraphQLSerializer = GraphQLSerializer.JACKSON
 ) {
-    val classNameCache: MutableMap<String, MutableList<ClassName>> = mutableMapOf()
-    val typeSpecs: MutableMap<String, TypeSpec> = mutableMapOf()
+    val typeSpecs: MutableMap<ClassName, TypeSpec> = mutableMapOf()
+    val polymorphicTypes: MutableMap<ClassName, MutableList<ClassName>> = mutableMapOf()
+
+    // shared types
+    val enumClassToTypeSpecs: MutableMap<ClassName, TypeSpec> = mutableMapOf()
+    val inputClassToTypeSpecs: MutableMap<ClassName, TypeSpec> = mutableMapOf()
+    val scalarsClassToTypeSpec: MutableMap<ClassName, MutableList<TypeSpec>> = mutableMapOf()
     val typeAliases: MutableMap<String, TypeAliasSpec> = mutableMapOf()
 
+    // class name and type selection caches
+    val classNameCache: MutableMap<String, MutableList<ClassName>> = mutableMapOf()
     val typeToSelectionSetMap: MutableMap<String, Set<String>> = mutableMapOf()
 }