Remove GraphQLID annotation for ID class (ExpediaGroup#700)

* Add ID wrapper class

Add a simple wrapper class that will allow us to support List<ID>

Fixes ExpediaGroup#698

* Remove @GraphQLID annotation

* Add more unit tests for coverage

* Update docs/writing-schemas/scalars.md

Co-authored-by: Dariusz Kuc <[email protected]>

* Update docs to match example code

* Update docs language

Co-authored-by: Shane Myrick <[email protected]>
Co-authored-by: Dariusz Kuc <[email protected]>

Author: 3 people

docs/writing-schemas/annotations.md

@@ -6,10 +6,8 @@ title: Annotations
 `graphql-kotlin-schema-generator` ships with a number of annotation classes to allow you to enhance your GraphQL schema
 for things that can't be directly derived from Kotlin reflection.
 
-* [@GraphQLContext](../execution/contextual-data) - Autowire `GraphQLContext` from the environment
 * [@GraphQLDescription](../customizing-schemas/documenting-fields) - Provide a description for a GraphQL field
 * [@GraphQLDirective](../customizing-schemas/directives) - Registers directive on a GraphQL field
-* [@GraphQLID](scalars#id) - Marks given field as GraphQL `ID`
 * [@GraphQLIgnore](../customizing-schemas/excluding-fields) - Exclude field from the GraphQL schema
 * [@GraphQLName](../customizing-schemas/renaming-fields) - Override the name used for the type
 * Kotlin built in [@Deprecated](../customizing-schemas/deprecating-schema) - Apply the GraphQL `@deprecated` directive on the field

docs/writing-schemas/scalars.md

@@ -24,40 +24,39 @@ extended scalar types provided by `graphql-java`.
 
 ## ID
 
-GraphQL supports a the scalar type ID, a unique identifier that is not intended to be human readable. ID's are
-serialized as a String. To mark given field as an ID field you have to annotate it with `@GraphQLID` annotation.
+GraphQL supports the scalar type `ID`, a unique identifier that is not intended to be human readable. IDs are
+serialized as a `String`. To expose a GraphQL `ID` field, you must use the `com.expediagroup.graphql.types.ID` class, which wraps the underlying `String` value.
+
 
 > NOTE: `graphql-java` supports additional types (`String`, `Int`, `Long`, or `UUID`) but [due to serialization issues](https://github.com/ExpediaGroup/graphql-kotlin/issues/317) we can only directly support Strings. You can still use a type like UUID internally just as long as you convert or parse the value yourself and handle the errors.
 
 ```kotlin
 data class Person(
-  @GraphQLID
-  val id: String,
-  val name: String
+    val id: ID,
+    val name: String
 )
 
-fun locatePerson(@GraphQLID id: String) = Person(id, "Jane Doe")
+fun findPersonById(id: ID) = Person(id, "John Smith")
 
-@GraphQLID
-fun generateRandomId() = UUID.randomUUID().toString()
+fun generateRandomId(): ID = ID(UUID.randomUUID().toString())
 ```
 
 This would produce the following schema:
 
 ```graphql
 schema {
-  query: Query
+    query: Query
 }
 
 
 type Query {
-  locatePerson(id: ID!): Person!
-  generateRandomId: ID!
+    findPersonById(id: ID!): Person!
+    generateRandomId: ID!
 }
 
 type Person {
-  id: ID!
-  name: String!
+    id: ID!
+    name: String!
 }
 ```
 

examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/ScalarQuery.kt

@@ -17,9 +17,9 @@
 package com.expediagroup.graphql.examples.query
 
 import com.expediagroup.graphql.annotations.GraphQLDescription
-import com.expediagroup.graphql.annotations.GraphQLID
 import com.expediagroup.graphql.spring.operations.Mutation
 import com.expediagroup.graphql.spring.operations.Query
+import com.expediagroup.graphql.types.ID
 import org.springframework.stereotype.Component
 import java.util.UUID
 
@@ -35,11 +35,10 @@ class ScalarQuery : Query {
     @GraphQLDescription("Prints a string with a custom scalar as input")
     fun printUuids(uuids: List<UUID>) = "You sent $uuids"
 
-    fun findPersonById(@GraphQLID id: String) = Person(id, "Nelson")
+    fun findPersonById(id: ID) = Person(id, "Nelson")
 
     @GraphQLDescription("generates random GraphQL ID")
-    @GraphQLID
-    fun generateRandomId() = UUID.randomUUID().toString()
+    fun generateRandomId() = ID(UUID.randomUUID().toString())
 }
 
 @Component
@@ -48,7 +47,6 @@ class ScalarMutation : Mutation {
 }
 
 data class Person(
-    @GraphQLID
-    val id: String,
+    val id: ID,
     val name: String
 )

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

@@ -17,7 +17,6 @@
 package com.expediagroup.graphql.generator.extensions
 
 import com.expediagroup.graphql.annotations.GraphQLDescription
-import com.expediagroup.graphql.annotations.GraphQLID
 import com.expediagroup.graphql.annotations.GraphQLIgnore
 import com.expediagroup.graphql.annotations.GraphQLName
 import kotlin.reflect.KAnnotatedElement
@@ -31,8 +30,6 @@ internal fun KAnnotatedElement.getDeprecationReason(): String? = this.findAnnota
 
 internal fun KAnnotatedElement.isGraphQLIgnored(): Boolean = this.findAnnotation<GraphQLIgnore>() != null
 
-internal fun KAnnotatedElement.isGraphQLID(): Boolean = this.findAnnotation<GraphQLID>() != null
-
 internal fun Deprecated.getReason(): String? {
     val builder = StringBuilder()
     builder.append(this.message)

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

@@ -24,12 +24,6 @@ import kotlin.reflect.KProperty
  * For properties we need to check both the property for annotations and the constructor argument
  */
 
-internal fun KProperty<*>.isPropertyGraphQLID(parentClass: KClass<*>): Boolean = when {
-    this.isGraphQLID() -> true
-    getConstructorParameter(parentClass)?.isGraphQLID().isTrue() -> true
-    else -> false
-}
-
 internal fun KProperty<*>.isPropertyGraphQLIgnored(parentClass: KClass<*>): Boolean = when {
     this.isGraphQLIgnored() -> true
     getConstructorParameter(parentClass)?.isGraphQLIgnored().isTrue() -> true

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

@@ -20,7 +20,6 @@ import com.expediagroup.graphql.exceptions.InvalidInputFieldTypeException
 import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.extensions.getGraphQLDescription
 import com.expediagroup.graphql.generator.extensions.getName
-import com.expediagroup.graphql.generator.extensions.isGraphQLID
 import com.expediagroup.graphql.generator.extensions.isInterface
 import com.expediagroup.graphql.generator.extensions.isList
 import com.expediagroup.graphql.generator.extensions.safeCast
@@ -34,7 +33,7 @@ internal fun generateArgument(generator: SchemaGenerator, parameter: KParameter)
         throw InvalidInputFieldTypeException(parameter)
     }
 
-    val graphQLType = generateGraphQLType(generator, parameter.type, inputType = true, annotatedAsID = parameter.isGraphQLID())
+    val graphQLType = generateGraphQLType(generator = generator, type = parameter.type, inputType = true)
 
     // Deprecation of arguments is currently unsupported: https://github.com/facebook/graphql/issues/197
     val builder = GraphQLArgument.newArgument()

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

@@ -22,7 +22,6 @@ import com.expediagroup.graphql.generator.extensions.getDeprecationReason
 import com.expediagroup.graphql.generator.extensions.getFunctionName
 import com.expediagroup.graphql.generator.extensions.getGraphQLDescription
 import com.expediagroup.graphql.generator.extensions.getValidArguments
-import com.expediagroup.graphql.generator.extensions.isGraphQLID
 import com.expediagroup.graphql.generator.extensions.safeCast
 import com.expediagroup.graphql.generator.types.utils.getWrappedReturnType
 import graphql.schema.FieldCoordinates
@@ -51,7 +50,7 @@ internal fun generateFunction(generator: SchemaGenerator, fn: KFunction<*>, pare
 
     val typeFromHooks = generator.config.hooks.willResolveMonad(fn.returnType)
     val returnType = getWrappedReturnType(typeFromHooks)
-    val graphQLOutputType = generateGraphQLType(generator, returnType, annotatedAsID = fn.isGraphQLID()).safeCast<GraphQLOutputType>()
+    val graphQLOutputType = generateGraphQLType(generator = generator, type = returnType).safeCast<GraphQLOutputType>()
     val graphQLType = builder.type(graphQLOutputType).build()
     val coordinates = FieldCoordinates.coordinates(parentName, functionName)
 

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

@@ -33,10 +33,10 @@ 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, annotatedAsID: Boolean = false): GraphQLType {
+internal fun generateGraphQLType(generator: SchemaGenerator, type: KType, inputType: Boolean = false): GraphQLType {
     val hookGraphQLType = generator.config.hooks.willGenerateGraphQLType(type)
     val graphQLType = hookGraphQLType
-        ?: generateScalar(generator, type, annotatedAsID)
+        ?: generateScalar(generator, type)
         ?: objectFromReflection(generator, type, inputType)
 
     // Do not call the hook on GraphQLTypeReference as we have not generated the type yet

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

@@ -19,7 +19,6 @@ package com.expediagroup.graphql.generator.types
 import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.extensions.getPropertyDescription
 import com.expediagroup.graphql.generator.extensions.getPropertyName
-import com.expediagroup.graphql.generator.extensions.isPropertyGraphQLID
 import com.expediagroup.graphql.generator.extensions.safeCast
 import graphql.schema.GraphQLInputObjectField
 import graphql.schema.GraphQLInputType
@@ -28,7 +27,7 @@ import kotlin.reflect.KProperty
 
 internal fun generateInputProperty(generator: SchemaGenerator, prop: KProperty<*>, parentClass: KClass<*>): GraphQLInputObjectField {
     val builder = GraphQLInputObjectField.newInputObjectField()
-    val graphQLInputType = generateGraphQLType(generator, prop.returnType, true, prop.isPropertyGraphQLID(parentClass)).safeCast<GraphQLInputType>()
+    val graphQLInputType = generateGraphQLType(generator = generator, type = prop.returnType, inputType = true).safeCast<GraphQLInputType>()
 
     builder.description(prop.getPropertyDescription(parentClass))
     builder.name(prop.getPropertyName(parentClass))

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

@@ -22,7 +22,6 @@ import com.expediagroup.graphql.generator.extensions.getPropertyDeprecationReaso
 import com.expediagroup.graphql.generator.extensions.getPropertyDescription
 import com.expediagroup.graphql.generator.extensions.getPropertyName
 import com.expediagroup.graphql.generator.extensions.getSimpleName
-import com.expediagroup.graphql.generator.extensions.isPropertyGraphQLID
 import com.expediagroup.graphql.generator.extensions.safeCast
 import graphql.schema.FieldCoordinates
 import graphql.schema.GraphQLFieldDefinition
@@ -31,7 +30,7 @@ import kotlin.reflect.KClass
 import kotlin.reflect.KProperty
 
 internal fun generateProperty(generator: SchemaGenerator, prop: KProperty<*>, parentClass: KClass<*>): GraphQLFieldDefinition {
-    val propertyType = generateGraphQLType(generator, type = prop.returnType, annotatedAsID = prop.isPropertyGraphQLID(parentClass))
+    val propertyType = generateGraphQLType(generator, type = prop.returnType)
         .safeCast<GraphQLOutputType>()
 
     val fieldBuilder = GraphQLFieldDefinition.newFieldDefinition()

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

@@ -16,39 +16,26 @@
 
 package com.expediagroup.graphql.generator.types
 
-import com.expediagroup.graphql.exceptions.InvalidIdTypeException
 import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.extensions.getKClass
 import com.expediagroup.graphql.generator.extensions.safeCast
+import com.expediagroup.graphql.types.ID
 import graphql.Scalars
 import graphql.schema.GraphQLScalarType
 import java.math.BigDecimal
 import java.math.BigInteger
 import kotlin.reflect.KClass
 import kotlin.reflect.KType
-import kotlin.reflect.full.isSubclassOf
 
-internal fun generateScalar(generator: SchemaGenerator, type: KType, annotatedAsID: Boolean): GraphQLScalarType? {
-    val kClass = type.getKClass()
-    val scalar = when {
-        annotatedAsID -> getId(kClass)
-        else -> defaultScalarsMap[kClass]
-    }
+internal fun generateScalar(generator: SchemaGenerator, type: KType): GraphQLScalarType? {
+    val kClass: KClass<*> = type.getKClass()
+    val scalar: GraphQLScalarType? = defaultScalarsMap[kClass]
 
     return scalar?.let {
         generator.config.hooks.onRewireGraphQLType(it).safeCast()
     }
 }
 
-@Throws(InvalidIdTypeException::class)
-private fun getId(kClass: KClass<*>): GraphQLScalarType? {
-    return if (kClass.isSubclassOf(String::class)) {
-        Scalars.GraphQLID
-    } else {
-        throw InvalidIdTypeException(kClass)
-    }
-}
-
 private val defaultScalarsMap = mapOf(
     Int::class to Scalars.GraphQLInt,
     Long::class to Scalars.GraphQLLong,
@@ -59,5 +46,6 @@ private val defaultScalarsMap = mapOf(
     BigInteger::class to Scalars.GraphQLBigInteger,
     Char::class to Scalars.GraphQLChar,
     String::class to Scalars.GraphQLString,
-    Boolean::class to Scalars.GraphQLBoolean
+    Boolean::class to Scalars.GraphQLBoolean,
+    ID::class to Scalars.GraphQLID
 )

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Expedia, Inc
+ * Copyright 2020 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,12 +14,16 @@
  * limitations under the License.
  */
 
-package com.expediagroup.graphql.exceptions
+package com.expediagroup.graphql.types
 
-import kotlin.reflect.KClass
+import com.fasterxml.jackson.annotation.JsonIgnore
+import com.fasterxml.jackson.annotation.JsonValue
 
 /**
- * Throws when the KClass is not one of the supported types for a GraphQLID
+ * Used to represent a GraphQL ID scalar type
+ * which must serialize/deserialize to a string value
  */
-class InvalidIdTypeException(kClass: KClass<*>) :
-    GraphQLKotlinException("${kClass.simpleName} is not a valid ID type, only Strings are accepted")
+data class ID(@get:JsonIgnore val value: String) {
+    @JsonValue
+    override fun toString() = value
+}

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/exceptions/InvalidIdTypeException.kt renamed to graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/types/ID.kt

@@ -19,12 +19,12 @@ package com.expediagroup.graphql.extensions
 import com.expediagroup.graphql.TopLevelObject
 import com.expediagroup.graphql.annotations.GraphQLDescription
 import com.expediagroup.graphql.annotations.GraphQLDirective
-import com.expediagroup.graphql.annotations.GraphQLID
 import com.expediagroup.graphql.annotations.GraphQLIgnore
 import com.expediagroup.graphql.annotations.GraphQLName
 import com.expediagroup.graphql.getTestSchemaConfigWithMockedDirectives
 import com.expediagroup.graphql.testSchemaConfig
 import com.expediagroup.graphql.toSchema
+import com.expediagroup.graphql.types.ID
 import graphql.introspection.Introspection
 import graphql.schema.GraphQLSchema
 import org.junit.jupiter.api.Test
@@ -123,12 +123,11 @@ class GraphQLSchemaExtensionsTest {
     }
 
     class QueryWithId {
-        fun queryById(@GraphQLID id: String) = TypeWithId(id, "junit")
+        fun queryById(id: ID) = TypeWithId(id, "junit")
     }
 
     class TypeWithId(
-        @GraphQLID
-        val id: String,
+        val id: ID,
         val name: String
     )