Standardize the creation and usage of custom directives (#10)

* Standardize the creation and usage of custom directives

* Remove @GraphQLExperimental

* Pruning builtin directive support

* Add custom directive to the schema definition

* Add directive created from object type to the schema

* Assert the present of custom directive in the schema

* Add naming convention to the directive doc

* Applying directive naming convention to the deprecated directive

Author: gscheibel

README.md

@@ -528,7 +528,10 @@ schema {
 
 type TopLevelQuery {
 
-  """DEPRECATED: old query that should not be used always returns false"""
+  """old query that should not be used always returns false
+  
+  Directives: deprecated
+  """
   simpleDeprecatedQuery: Boolean! @deprecated(reason: "this query is deprecated, replace with shinyNewQuery")
 
   """new query that always returns true"""
@@ -538,34 +541,48 @@ type TopLevelQuery {
 
 While you can deprecate any fields/methods in your code, GraphQL only supports deprecation directive on the queries, mutations and output types. All deprecated objects will have "DEPRECATED" prefix in their description.
 
-### `@GraphQLExperimental`
 
-Schemas are often evoling over time and while some feature are getting removed others can be added. Some of those new features may be experimental meaning they are still being tested out and can change without any notice. Functions annotated with `@GraphQLExperimental` annotations will have set `@experimental` directive. You can access those directives during instrumentation to provide some custom logic. Experimental methods will also have `EXPERIMENTAL` prefix in their description.
+### Custom directives
+
+Custom directives can be added to the schema using custom annotations:
 
 ```kotlin
-class SimpleQuery {
+@GraphQLDirective(
+        name = "Awesome",
+        description = "This element is great",
+        locations = [FIELD, FIELD_DEFINITION]
+)
+annotation class AwesomeDirective(val value: String)
 
-    /*
-    * NOTE: currently GraphQL directives are not exposed in the schema through introspection but they
-    * are available on the server that exposes the schema
-    */
-    @GraphQLExperimental("this is an experimental feature")
-    @GraphQLDescription("echoes back the msg")
-    fun experimentalEcho(msg: String): String = msg
+class MyQuery {
+    @AwesomeDirective("cool stuff")
+    val somethingGreat: String = "Hello World"
 }
 ```
 
+The directive will then added to the schema as:
 
-Will translate to
 ```graphql
-type TopLevelQuery {
-  """EXPERIMENTAL: echoes back the msg"""
-  experimentalEcho(msg: String!): String!
+# This element is great
+directive @awesome(value: String) on FIELD | FIELD_DEFINITION
+
+# Directives: awesome 
+type MyQuery {
+   somethingGreat: String @awesome("cool stuff")
 }
 ```
 
+Directives can be added to various places in the schema, to see the full list see the [graphql.introspection.Introspection.DirectiveLocation enum](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/introspection/Introspection.java#L296) from graphql-java.
+
 Note that GraphQL directives are currently not available through introspection. See: https://github.com/facebook/graphql/issues/300 and https://github.com/graphql-java/graphql-java/issues/1017 for more details.
 
+#### Naming Convention
+
+As described in the example above, the directive name in the schema will by default come from the `@GraphQLDirective.name` attribute.
+If this value is not specified like an empty string, the directive name will be the name of the annotated annotation (eg: `AwesomeDirective`). 
+
+For more readibility, the name used by the schema will be decapitalized so `Awesome` becomes `awesome` and `AwesomeDirective` would be `awesomeDirective`.
+
 ## Configuration
 
 ### Documentation Enforcement

example/src/main/kotlin/com.expedia.graphql.sample/directives/CustomDirective.kt

@@ -0,0 +1,11 @@
+package com.expedia.graphql.sample.directives
+
+import com.expedia.graphql.annotations.GraphQLDirective
+import graphql.introspection.Introspection.DirectiveLocation.FIELD
+
+@GraphQLDirective(
+        name = "CustomMarkup",
+        description = "Add markup to a field",
+        locations = [FIELD]
+)
+annotation class CustomDirective

example/src/main/kotlin/com.expedia.graphql.sample/query/SimpleQuery.kt

@@ -1,8 +1,8 @@
 package com.expedia.graphql.sample.query
 
 import com.expedia.graphql.annotations.GraphQLDescription
-import com.expedia.graphql.annotations.GraphQLExperimental
 import com.expedia.graphql.annotations.GraphQLIgnore
+import com.expedia.graphql.sample.directives.CustomDirective
 import org.springframework.stereotype.Component
 import java.util.Random
 
@@ -19,11 +19,6 @@ class SimpleQuery: Query {
     @GraphQLDescription("new query that always returns true")
     fun shinyNewQuery(): Boolean = true
 
-    /*
-    * NOTE: currently GraphQL directives are not exposed in the schema through introspection but they
-    * are available on the server that exposes the schema
-    */
-    @GraphQLExperimental("this is an experimental feature")
     @GraphQLDescription("echoes back the msg")
     fun experimentalEcho(msg: String): String = msg
 
@@ -33,7 +28,9 @@ class SimpleQuery: Query {
     private fun privateFunctionsAreNotVisible() = "ignored private function"
 
     @GraphQLDescription("performs some operation")
-    fun doSomething(@GraphQLDescription("super important value") value: Int): Boolean = true
+    @CustomDirective
+    fun doSomething(@GraphQLDescription("super important value")
+                    value: Int): Boolean = true
 
     @GraphQLDescription("generates pseudo random int and returns it if it is less than 50")
     fun generateNullableNumber(): Int? {

src/main/kotlin/com/expedia/graphql/annotations/GraphQLDirective.kt

@@ -1,7 +1,18 @@
 package com.expedia.graphql.annotations
 
+import graphql.introspection.Introspection.DirectiveLocation
+import graphql.introspection.Introspection.DirectiveLocation.QUERY
+import graphql.introspection.Introspection.DirectiveLocation.MUTATION
+import graphql.introspection.Introspection.DirectiveLocation.FIELD
+import graphql.introspection.Introspection.DirectiveLocation.FIELD_DEFINITION
+import graphql.introspection.Introspection.DirectiveLocation.OBJECT
+
 /**
  * Meta annotation used to denote an annotation as a GraphQL directive.
  */
 @Target(AnnotationTarget.ANNOTATION_CLASS)
-annotation class GraphQLDirective(val name: String = "")
+annotation class GraphQLDirective(
+        val name: String = "",
+        val description: String = "",
+        val locations: Array<DirectiveLocation> = [QUERY, MUTATION, FIELD, FIELD_DEFINITION, OBJECT]
+)

src/main/kotlin/com/expedia/graphql/annotations/GraphQLExperimental.kt

@@ -1,14 +1,14 @@
 package com.expedia.graphql.schema
 
 import com.expedia.graphql.TopLevelObjectDef
-import com.expedia.graphql.schema.directives.ExperimentalDirective
 import com.expedia.graphql.schema.exceptions.ConflictingTypesException
 import com.expedia.graphql.schema.exceptions.CouldNotGetNameOfEnumException
 import com.expedia.graphql.schema.exceptions.TypeNotSupportedException
 import com.expedia.graphql.schema.models.KGraphQLType
 import graphql.TypeResolutionEnvironment
 import graphql.schema.DataFetcher
 import graphql.schema.GraphQLArgument
+import graphql.schema.GraphQLDirective
 import graphql.schema.GraphQLEnumType
 import graphql.schema.GraphQLFieldDefinition
 import graphql.schema.GraphQLInputObjectField
@@ -40,11 +40,10 @@ internal class SchemaGenerator(
 
     private val typesCache: MutableMap<String, KGraphQLType> = mutableMapOf()
     private val additionTypes = mutableSetOf<GraphQLType>()
+    private val directives = mutableSetOf<GraphQLDirective>()
 
     internal fun generate(): GraphQLSchema {
         val builder = generateWithReflection()
-        builder.additionalDirective(ExperimentalDirective)
-        builder.additionalDirectives(config.directives)
         return config.hooks.willBuildSchema(builder).build()
     }
 
@@ -53,12 +52,13 @@ internal class SchemaGenerator(
         addQueries(builder)
         addMutations(builder)
         addAdditionalTypes(builder)
+        addDirectives(builder)
         return builder
     }
 
-    private fun addAdditionalTypes(builder: GraphQLSchema.Builder) {
-        builder.additionalTypes(additionTypes)
-    }
+    private fun addAdditionalTypes(builder: GraphQLSchema.Builder) = builder.additionalTypes(additionTypes)
+
+    private fun addDirectives(builder: GraphQLSchema.Builder)= builder.additionalDirectives(directives)
 
     private fun addQueries(builder: GraphQLSchema.Builder) {
         val queryBuilder = GraphQLObjectType.Builder()
@@ -104,8 +104,9 @@ internal class SchemaGenerator(
             builder.deprecate(it)
         }
 
-        if (fn.isGraphQLExperimental()) {
-            builder.withDirective(ExperimentalDirective)
+        fn.directives().forEach {
+            builder.withDirective(it)
+            directives.add(it)
         }
 
         val args = mutableMapOf<String, Parameter>()
@@ -227,6 +228,7 @@ internal class SchemaGenerator(
 
         klass.directives().map {
             builder.withDirective(it)
+            directives.add(it)
         }
 
         if (interfaceType != null) builder.withInterface(interfaceType)

src/main/kotlin/com/expedia/graphql/schema/SchemaGenerator.kt

@@ -11,6 +11,5 @@ data class SchemaGeneratorConfig(
     val supportedPackages: String,
     val topLevelQueryName: String = "TopLevelQuery",
     val topLevelMutationName: String = "TopLevelMutation",
-    val hooks: SchemaGeneratorHooks = NoopSchemaGeneratorHooks(),
-    val directives: Set<GraphQLDirective> = emptySet()
+    val hooks: SchemaGeneratorHooks = NoopSchemaGeneratorHooks()
 )

src/main/kotlin/com/expedia/graphql/schema/SchemaGeneratorConfig.kt

@@ -2,7 +2,6 @@ package com.expedia.graphql.schema
 
 import com.expedia.graphql.annotations.GraphQLContext
 import com.expedia.graphql.annotations.GraphQLDescription
-import com.expedia.graphql.annotations.GraphQLExperimental
 import com.expedia.graphql.annotations.GraphQLIgnore
 import com.expedia.graphql.schema.exceptions.CouldNotGetNameOfAnnotationException
 import com.google.common.base.CaseFormat
@@ -11,31 +10,49 @@ import graphql.schema.GraphQLDirective
 import graphql.schema.GraphQLInputType
 import kotlin.reflect.KAnnotatedElement
 import kotlin.reflect.KClass
+import kotlin.reflect.KFunction
 import kotlin.reflect.KParameter
+import kotlin.reflect.KProperty1
 import kotlin.reflect.KType
 import kotlin.reflect.full.declaredMemberFunctions
 import kotlin.reflect.full.findAnnotation
+import kotlin.reflect.full.memberProperties
 import com.expedia.graphql.annotations.GraphQLDirective as DirectiveAnnotation
 
 internal fun KAnnotatedElement.graphQLDescription(): String? {
-    var prefix = this.getDeprecationReason()?.let { "DEPRECATED" }
-    if (null == prefix && this.isGraphQLExperimental()) {
-        prefix = "EXPERIMENTAL"
-    }
+    val directiveNames = listOfDirectives().map { it.normalizeDirectiveName() }
 
     val description = this.findAnnotation<GraphQLDescription>()?.value
 
-    return if (null != description) {
-        if (null != prefix) {
-            "$prefix: $description"
-        } else {
-            description
+    return when {
+        description != null && directiveNames.isNotEmpty() -> {
+            """$description
+            |
+            |Directives: ${directiveNames.joinToString(", ")}
+            """.trimMargin()
+            }
+        description == null && directiveNames.isNotEmpty() -> {
+            "Directives: ${directiveNames.joinToString(", ")}"
         }
-    } else {
-        prefix
+        else -> description
     }
 }
 
+private fun KAnnotatedElement.listOfDirectives(): List<String> {
+    val directiveNames = mutableListOf(this.getDeprecationReason()?.let { "deprecated" })
+
+    directiveNames.addAll(this.annotations
+            .filter { it.getDirectiveInfo() != null }
+            .map {
+                when {
+                    it.getDirectiveInfo()?.name != "" -> "@${it.getDirectiveInfo()?.name}"
+                    else -> "@${it.annotationClass.simpleName}"
+                }
+            }
+    )
+    return directiveNames.filterNotNull()
+}
+
 internal fun KType.graphQLDescription(): String? = (classifier as? KClass<*>)?.graphQLDescription()
 
 internal fun KAnnotatedElement.getDeprecationReason(): String? {
@@ -51,8 +68,6 @@ internal fun KAnnotatedElement.getDeprecationReason(): String? {
 
 internal fun KAnnotatedElement.isGraphQLIgnored() = this.findAnnotation<GraphQLIgnore>() != null
 
-internal fun KAnnotatedElement.isGraphQLExperimental() = this.findAnnotation<GraphQLExperimental>() != null
-
 internal fun Annotation.getDirectiveInfo() =
     this.annotationClass.annotations.find { it is DirectiveAnnotation } as? DirectiveAnnotation
 
@@ -67,18 +82,22 @@ internal fun KAnnotatedElement.directives() =
             } else {
                 annotation.annotationClass.simpleName ?: throw CouldNotGetNameOfAnnotationException(annotation.annotationClass)
             }
-            builder.name(CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, name))
+            builder.name(name.normalizeDirectiveName())
+                .validLocations(*directiveInfo.locations)
+                .description(directiveInfo.description)
 
-            annotation::class.properties().forEach { prop ->
+            annotation::class.properties().forEach{ prop ->
                 val propertyName = prop.name
                 val value = prop.call(annotation)
                 @Suppress("Detekt.UnsafeCast")
                 val type = graphQLScalar(prop.returnType) as GraphQLInputType
                 builder.argument(GraphQLArgument.newArgument().name(propertyName).value(value).type(type).build())
             }
 
-            builder.build()
-        }
+        builder.build()
     }
+}
 
 internal fun KParameter.isGraphQLContext() = this.findAnnotation<GraphQLContext>() != null
+
+private fun String.normalizeDirectiveName() = CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, this)