Custom types with annotation (#1298)

### 📝 Description
This adds a new annotation `@GraphQLType` which you can use to specify the return type of any field to be different than the Kotlin type. It explicitly takes a string for the type name and not just another `KClass` reference, because what we can do is return the field type as a type reference, but then allow devs to specify custom additional types that they have built up with their own GraphQLType builders.

The prime use case for this is what we were trying to accomplish with `@GraphQLUnion`. In the scenario where you want to define a new union that is many different Kotlin classes but maybe those come from other libraries and you can't modify the class to have it implement the empty interface, this can solve that solution. But now you can also specify directives, descriptions, and deprecations on the type. Plus this solution scales beyond just unions and can work for any custom type that you can define in Kotlin code. 

If we feel like this is a decent approach, I would even consider deprecating the `@GraphQLUnion` annotation in favor of this generic approach that anyone can use and even extend now that we have added the ability to pass in `GraphQLType`s in the config.

### 🔗 Related Issues

Author: smyrick

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/SchemaGenerator.kt

@@ -20,6 +20,7 @@ import com.expediagroup.graphql.generator.exceptions.InvalidPackagesException
 import com.expediagroup.graphql.generator.internal.state.AdditionalType
 import com.expediagroup.graphql.generator.internal.state.ClassScanner
 import com.expediagroup.graphql.generator.internal.state.TypesCache
+import com.expediagroup.graphql.generator.internal.types.GraphQLKTypeMetadata
 import com.expediagroup.graphql.generator.internal.types.generateGraphQLType
 import com.expediagroup.graphql.generator.internal.types.generateMutations
 import com.expediagroup.graphql.generator.internal.types.generateQueries
@@ -109,18 +110,18 @@ open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeab
      * Generate the GraphQL type for all the `additionalTypes`.
      *
      * If you need to provide more custom additional types that were not picked up from reflection of the schema objects,
-     * you can provide more types to be added through [generateSchema].
+     * you can provide more types to be added through [generateSchema] or the config.
      *
      * This function loops because while generating the additionalTypes it is possible to create more additional types that need to be processed.
      */
     protected fun generateAdditionalTypes(): Set<GraphQLType> {
-        val graphqlTypes = mutableSetOf<GraphQLType>()
+        val graphqlTypes = this.config.additionalTypes.toMutableSet()
         while (this.additionalTypes.isNotEmpty()) {
             val currentlyProcessedTypes = LinkedHashSet(this.additionalTypes)
             this.additionalTypes.clear()
             graphqlTypes.addAll(
                 currentlyProcessedTypes.map {
-                    GraphQLTypeUtil.unwrapNonNull(generateGraphQLType(this, it.kType, it.inputType))
+                    GraphQLTypeUtil.unwrapNonNull(generateGraphQLType(this, it.kType, GraphQLKTypeMetadata(inputType = it.inputType)))
                 }
             )
         }

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/SchemaGeneratorConfig.kt

@@ -20,6 +20,7 @@ import com.expediagroup.graphql.generator.execution.KotlinDataFetcherFactoryProv
 import com.expediagroup.graphql.generator.execution.SimpleKotlinDataFetcherFactoryProvider
 import com.expediagroup.graphql.generator.hooks.NoopSchemaGeneratorHooks
 import com.expediagroup.graphql.generator.hooks.SchemaGeneratorHooks
+import graphql.schema.GraphQLType
 
 /**
  * Settings for generating the schema.
@@ -29,5 +30,6 @@ open class SchemaGeneratorConfig(
     open val topLevelNames: TopLevelNames = TopLevelNames(),
     open val hooks: SchemaGeneratorHooks = NoopSchemaGeneratorHooks,
     open val dataFetcherFactoryProvider: KotlinDataFetcherFactoryProvider = SimpleKotlinDataFetcherFactoryProvider(),
-    open val introspectionEnabled: Boolean = true
+    open val introspectionEnabled: Boolean = true,
+    open val additionalTypes: Set<GraphQLType> = emptySet()
 )

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/annotations/GraphQLType.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2021 Expedia, Inc
+ *
+ * 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
+ *
+ *     https://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.expediagroup.graphql.generator.annotations
+
+/**
+ * Can be used on any field to set the return type.
+ * The type name must match exactly to some additional type that was provided to the schema
+ * generator, or it will fail on building the schema.
+ *
+ * Internally, the generator will check for this anntation first and just return a type reference with this name
+ * instead of running reflection on the Kotlin code. This means that you can use this annotation with any Kotlin return type.
+ * That does mean you could have runtime exceptions if the model you actually return doesn't match the GraphQL schema type.
+ */
+annotation class GraphQLType(val typeName: String)

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/extensions/annotationExtensions.kt

@@ -19,6 +19,7 @@ package com.expediagroup.graphql.generator.internal.extensions
 import com.expediagroup.graphql.generator.annotations.GraphQLDescription
 import com.expediagroup.graphql.generator.annotations.GraphQLIgnore
 import com.expediagroup.graphql.generator.annotations.GraphQLName
+import com.expediagroup.graphql.generator.annotations.GraphQLType
 import com.expediagroup.graphql.generator.annotations.GraphQLUnion
 import kotlin.reflect.KAnnotatedElement
 import kotlin.reflect.full.findAnnotation
@@ -33,6 +34,8 @@ internal fun KAnnotatedElement.isGraphQLIgnored(): Boolean = this.findAnnotation
 
 internal fun List<Annotation>.getUnionAnnotation(): GraphQLUnion? = this.filterIsInstance(GraphQLUnion::class.java).firstOrNull()
 
+internal fun List<Annotation>.getCustomTypeAnnotation(): GraphQLType? = this.filterIsInstance(GraphQLType::class.java).firstOrNull()
+
 internal fun Deprecated.getReason(): String {
     val builder = StringBuilder()
     builder.append(this.message)

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/state/TypesCache.kt

@@ -20,12 +20,14 @@ import com.expediagroup.graphql.generator.annotations.GraphQLUnion
 import com.expediagroup.graphql.generator.exceptions.ConflictingTypesException
 import com.expediagroup.graphql.generator.exceptions.InvalidCustomUnionException
 import com.expediagroup.graphql.generator.exceptions.TypeNotSupportedException
+import com.expediagroup.graphql.generator.internal.extensions.getCustomTypeAnnotation
 import com.expediagroup.graphql.generator.internal.extensions.getKClass
 import com.expediagroup.graphql.generator.internal.extensions.getSimpleName
 import com.expediagroup.graphql.generator.internal.extensions.getUnionAnnotation
 import com.expediagroup.graphql.generator.internal.extensions.isAnnotationUnion
 import com.expediagroup.graphql.generator.internal.extensions.isListType
 import com.expediagroup.graphql.generator.internal.extensions.qualifiedName
+import com.expediagroup.graphql.generator.internal.types.GraphQLKTypeMetadata
 import graphql.schema.GraphQLNamedType
 import graphql.schema.GraphQLType
 import graphql.schema.GraphQLTypeReference
@@ -40,8 +42,8 @@ internal class TypesCache(private val supportedPackages: List<String>) : Closeab
     private val cache: MutableMap<String, KGraphQLType> = mutableMapOf()
     private val typesUnderConstruction: MutableSet<TypesCacheKey> = mutableSetOf()
 
-    internal fun get(type: KType, inputType: Boolean, annotations: List<Annotation>): GraphQLNamedType? {
-        val cacheKey = generateCacheKey(type, inputType, annotations)
+    internal fun get(type: KType, typeInfo: GraphQLKTypeMetadata): GraphQLNamedType? {
+        val cacheKey = generateCacheKey(type, typeInfo)
         return get(cacheKey)
     }
 
@@ -73,22 +75,26 @@ internal class TypesCache(private val supportedPackages: List<String>) : Closeab
         return null
     }
 
-    private fun generateCacheKey(type: KType, inputType: Boolean, annotations: List<Annotation> = emptyList()): TypesCacheKey {
+    private fun generateCacheKey(type: KType, typeInfo: GraphQLKTypeMetadata): TypesCacheKey {
         if (type.getKClass().isListType()) {
-            return TypesCacheKey(type, inputType)
+            return TypesCacheKey(type, typeInfo.inputType)
         }
 
-        val unionAnnotation = annotations.getUnionAnnotation()
+        val customTypeAnnotation = typeInfo.fieldAnnotations.getCustomTypeAnnotation()
+        if (customTypeAnnotation != null) {
+            return TypesCacheKey(type, typeInfo.inputType, customTypeAnnotation.typeName)
+        }
 
-        return if (unionAnnotation != null) {
-            if (type.getKClass().isAnnotationUnion(annotations)) {
-                TypesCacheKey(type = type, inputType = inputType, name = getCustomUnionNameKey(unionAnnotation))
+        val unionAnnotation = typeInfo.fieldAnnotations.getUnionAnnotation()
+        if (unionAnnotation != null) {
+            if (type.getKClass().isAnnotationUnion(typeInfo.fieldAnnotations)) {
+                return TypesCacheKey(type, typeInfo.inputType, getCustomUnionNameKey(unionAnnotation))
             } else {
                 throw InvalidCustomUnionException(type)
             }
-        } else {
-            TypesCacheKey(type = type, inputType = inputType)
         }
+
+        return TypesCacheKey(type, typeInfo.inputType)
     }
 
     private fun getCustomUnionNameKey(union: GraphQLUnion): String {
@@ -128,16 +134,16 @@ internal class TypesCache(private val supportedPackages: List<String>) : Closeab
 
     private fun isTypeNotSupported(type: KType): Boolean = supportedPackages.none { type.qualifiedName.startsWith(it) }
 
-    internal fun buildIfNotUnderConstruction(kClass: KClass<*>, inputType: Boolean, annotations: List<Annotation>, build: (KClass<*>) -> GraphQLType): GraphQLType {
+    internal fun buildIfNotUnderConstruction(kClass: KClass<*>, typeInfo: GraphQLKTypeMetadata, build: (KClass<*>) -> GraphQLType): GraphQLType {
         if (kClass.isListType()) {
             return build(kClass)
         }
 
-        val cacheKey = generateCacheKey(kClass.starProjectedType, inputType, annotations)
+        val cacheKey = generateCacheKey(kClass.starProjectedType, typeInfo)
         val cachedType = get(cacheKey)
         return when {
             cachedType != null -> cachedType
-            typesUnderConstruction.contains(cacheKey) -> GraphQLTypeReference.typeRef(kClass.getSimpleName(inputType))
+            typesUnderConstruction.contains(cacheKey) -> GraphQLTypeReference.typeRef(kClass.getSimpleName(typeInfo.inputType))
             else -> {
                 typesUnderConstruction.add(cacheKey)
                 val newType = build(kClass)

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/types/GraphQLKTypeMetadata.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2021 Expedia, Inc
+ *
+ * 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
+ *
+ *     https://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.expediagroup.graphql.generator.internal.types
+
+/**
+ * Internal metadata class we can use to forward info about the type we are generating.
+ * If there is no metadata to add, create the class with default values.
+ */
+internal data class GraphQLKTypeMetadata(
+    val inputType: Boolean = false,
+    val fieldName: String? = null,
+    val fieldAnnotations: List<Annotation> = emptyList()
+)

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/types/generateArgument.kt

@@ -47,7 +47,8 @@ internal fun generateArgument(generator: SchemaGenerator, parameter: KParameter)
         throw InvalidInputFieldTypeException(parameter)
     }
 
-    val graphQLType = generateGraphQLType(generator = generator, type = unwrappedType, inputType = true)
+    val typeInfo = GraphQLKTypeMetadata(inputType = true, fieldName = parameter.getName(), fieldAnnotations = parameter.annotations)
+    val graphQLType = generateGraphQLType(generator = generator, type = unwrappedType, typeInfo)
 
     // Deprecation of arguments is currently unsupported: https://github.com/facebook/graphql/issues/197
     val builder = GraphQLArgument.newArgument()

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/types/generateFunction.kt

@@ -51,7 +51,8 @@ internal fun generateFunction(generator: SchemaGenerator, fn: KFunction<*>, pare
 
     val typeFromHooks = generator.config.hooks.willResolveMonad(fn.returnType)
     val returnType = getWrappedReturnType(typeFromHooks)
-    val graphQLOutputType = generateGraphQLType(generator = generator, type = returnType, annotations = fn.annotations).safeCast<GraphQLOutputType>()
+    val typeInfo = GraphQLKTypeMetadata(fieldName = functionName, fieldAnnotations = fn.annotations)
+    val graphQLOutputType = generateGraphQLType(generator = generator, type = returnType, typeInfo).safeCast<GraphQLOutputType>()
     val graphQLType = builder.type(graphQLOutputType).build()
     val coordinates = FieldCoordinates.coordinates(parentName, functionName)
 

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/types/generateGraphQLType.kt

@@ -18,6 +18,7 @@ package com.expediagroup.graphql.generator.internal.types
 
 import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.extensions.unwrapType
+import com.expediagroup.graphql.generator.internal.extensions.getCustomTypeAnnotation
 import com.expediagroup.graphql.generator.internal.extensions.getKClass
 import com.expediagroup.graphql.generator.internal.extensions.getUnionAnnotation
 import com.expediagroup.graphql.generator.internal.extensions.isEnum
@@ -33,11 +34,11 @@ import kotlin.reflect.KType
 /**
  * Return a basic GraphQL type given all the information about the kotlin type.
  */
-internal fun generateGraphQLType(generator: SchemaGenerator, type: KType, inputType: Boolean = false, annotations: List<Annotation> = emptyList()): GraphQLType {
+internal fun generateGraphQLType(generator: SchemaGenerator, type: KType, typeInfo: GraphQLKTypeMetadata = GraphQLKTypeMetadata()): GraphQLType {
     val hookGraphQLType = generator.config.hooks.willGenerateGraphQLType(type)
     val graphQLType = hookGraphQLType
         ?: generateScalar(generator, type)
-        ?: objectFromReflection(generator, type, inputType, annotations)
+        ?: objectFromReflection(generator, type, typeInfo)
 
     // Do not call the hook on GraphQLTypeReference as we have not generated the type yet
     val unwrappedType = graphQLType.unwrapType()
@@ -49,26 +50,38 @@ internal fun generateGraphQLType(generator: SchemaGenerator, type: KType, inputT
     return typeWithNullability
 }
 
-private fun objectFromReflection(generator: SchemaGenerator, type: KType, inputType: Boolean, annotations: List<Annotation> = emptyList()): GraphQLType {
-    val cachedType = generator.cache.get(type, inputType, annotations)
+private fun objectFromReflection(generator: SchemaGenerator, type: KType, typeInfo: GraphQLKTypeMetadata): GraphQLType {
+    val cachedType = generator.cache.get(type, typeInfo)
 
     if (cachedType != null) {
         return cachedType
     }
 
     val kClass = type.getKClass()
 
-    return generator.cache.buildIfNotUnderConstruction(kClass, inputType, annotations) {
-        val graphQLType = getGraphQLType(generator, kClass, inputType, type, annotations)
+    return generator.cache.buildIfNotUnderConstruction(kClass, typeInfo) {
+        val graphQLType = getGraphQLType(generator, kClass, type, typeInfo)
         generator.config.hooks.willAddGraphQLTypeToSchema(type, graphQLType)
     }
 }
 
-private fun getGraphQLType(generator: SchemaGenerator, kClass: KClass<*>, inputType: Boolean, type: KType, fieldAnnotations: List<Annotation> = emptyList()): GraphQLType = when {
-    kClass.isEnum() -> @Suppress("UNCHECKED_CAST") (generateEnum(generator, kClass as KClass<Enum<*>>))
-    kClass.isListType() -> generateList(generator, type, inputType, fieldAnnotations)
-    kClass.isUnion(fieldAnnotations) -> generateUnion(generator, kClass, fieldAnnotations.getUnionAnnotation())
-    kClass.isInterface() -> generateInterface(generator, kClass)
-    inputType -> generateInputObject(generator, kClass)
-    else -> generateObject(generator, kClass)
+private fun getGraphQLType(
+    generator: SchemaGenerator,
+    kClass: KClass<*>,
+    type: KType,
+    typeInfo: GraphQLKTypeMetadata
+): GraphQLType {
+    val customTypeAnnotation = typeInfo.fieldAnnotations.getCustomTypeAnnotation()
+    if (customTypeAnnotation != null) {
+        return GraphQLTypeReference.typeRef(customTypeAnnotation.typeName)
+    }
+
+    return when {
+        kClass.isEnum() -> @Suppress("UNCHECKED_CAST") (generateEnum(generator, kClass as KClass<Enum<*>>))
+        kClass.isListType() -> generateList(generator, type, typeInfo)
+        kClass.isUnion(typeInfo.fieldAnnotations) -> generateUnion(generator, kClass, typeInfo.fieldAnnotations.getUnionAnnotation())
+        kClass.isInterface() -> generateInterface(generator, kClass)
+        typeInfo.inputType -> generateInputObject(generator, kClass)
+        else -> generateObject(generator, kClass)
+    }
 }

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/types/generateInputProperty.kt

@@ -17,6 +17,7 @@
 package com.expediagroup.graphql.generator.internal.types
 
 import com.expediagroup.graphql.generator.SchemaGenerator
+import com.expediagroup.graphql.generator.internal.extensions.getPropertyAnnotations
 import com.expediagroup.graphql.generator.internal.extensions.getPropertyDescription
 import com.expediagroup.graphql.generator.internal.extensions.getPropertyName
 import com.expediagroup.graphql.generator.internal.extensions.safeCast
@@ -33,10 +34,12 @@ internal fun generateInputProperty(generator: SchemaGenerator, prop: KProperty<*
     // Verfiy that the unwrapped GraphQL type is a valid input type
     val inputTypeFromHooks = generator.config.hooks.willResolveInputMonad(prop.returnType)
     val unwrappedType = inputTypeFromHooks.unwrapOptionalInputType()
-    val graphQLInputType = generateGraphQLType(generator = generator, type = unwrappedType, inputType = true).safeCast<GraphQLInputType>()
+    val propertyName = prop.getPropertyName(parentClass)
+    val typeInfo = GraphQLKTypeMetadata(inputType = true, fieldName = propertyName, fieldAnnotations = prop.getPropertyAnnotations(parentClass))
+    val graphQLInputType = generateGraphQLType(generator = generator, type = unwrappedType, typeInfo).safeCast<GraphQLInputType>()
 
+    builder.name(propertyName)
     builder.description(prop.getPropertyDescription(parentClass))
-    builder.name(prop.getPropertyName(parentClass))
     builder.type(graphQLInputType)
 
     generateDirectives(generator, prop, DirectiveLocation.INPUT_FIELD_DEFINITION, parentClass).forEach {