Update Apollo Kotlin specific directives to the latest version (#636)

* Update Apollo Kotlin specific directives to the latest version

* Add @defer definition

Author: BoD

resources/definitions/ApolloKotlin.graphql

@@ -1,27 +1,96 @@
-# Marks a field or variable definition as optional or required
-# By default Apollo Kotlin generates all variables of nullable types as optional, in compliance with the GraphQL specification,
-# but this can be configured with this directive, because if the variable was added in the first place, it's usually to pass a value
+# Taken from https://specs.apollo.dev/kotlin_labs/v0.2/kotlin_labs-v0.2.graphql
+
+"""
+Marks a field or variable definition as optional or required
+By default Apollo Kotlin generates all variables of nullable types as optional, in compliance with the GraphQL specification,
+but this can be configured with this directive, because if the variable was added in the first place, it's usually to pass a value
+Since: 3.0.0
+"""
 directive @optional(if: Boolean = true) on FIELD | VARIABLE_DEFINITION
 
-# Marks a field as non-null. The corresponding Kotlin property will be made non-nullable even if the GraphQL type is nullable.
-# When used on an object definition in a schema document, `fields` must be non-empty and contain a selection set of fields that should be non-null
-# When used on a field from an executable document, `fields` must always be empty
-#
-# Setting the directive at the schema level is usually easier as there is little reason that a field would be non-null in one place
-# and null in the other
+"""
+Marks a field as non-null. The corresponding Kotlin property will be made non-nullable even if the GraphQL type is nullable.
+When used on an object definition in a schema document, `fields` must be non-empty and contain a selection set of fields that should be non-null
+When used on a field from an executable document, `fields` must always be empty
+
+Setting the directive at the schema level is usually easier as there is little reason that a field would be non-null in one place
+and null in the other
+Since: 3.0.0
+"""
 directive @nonnull(fields: String! = "") on OBJECT | FIELD
 
-# Marks fields as key fields. Key fields are used to compute the cache key of an object
-# `keyFields` should contain a selection set. Composite fields are not supported yet.
-directive @typePolicy(keyFields: String!) on OBJECT | INTERFACE | UNION
+"""
+Attach extra information to a given type
+Since: 3.0.0
+"""
+directive @typePolicy(
+    """
+    a selection set containing fields used to compute the cache key of an object. Order is important.
+    """
+    keyFields: String! = "",
+    """
+    a selection set containing fields that shouldn't create a new cache Record and should be
+    embedded in their parent instead. Order is unimportant.
+    """
+    embeddedFields: String! = "",
+    """
+    a selection set containing fields that should be treated as Relay Connection fields. Order is unimportant.
+    Since: 3.4.1
+    """
+    connectionFields: String! = ""
+) on OBJECT | INTERFACE | UNION
+
+"""
+Attach extra information to a given field
+Since: 3.3.0
+"""
+directive @fieldPolicy(
+    forField: String!,
+    """
+    a list of arguments used to compute the cache key of the object this field is pointing to.
+    The list is parsed as a selection set: both spaces and comas are valid separators.
+    """
+    keyArgs: String! = "",
+    """
+    (experimental) a list of arguments that vary when requesting different pages.
+    These arguments are omitted when computing the cache key of this field.
+    The list is parsed as a selection set: both spaces and comas are valid separators.
+    Since: 3.4.1
+    """
+    paginationArgs: String! = ""
+) repeatable on OBJECT
+
+"""
+Indicates that the given field, argument, input field or enum value requires
+giving explicit consent before being used.
+Since: 3.3.1
+"""
+directive @requiresOptIn(feature: String!) repeatable
+on FIELD_DEFINITION
+    | ARGUMENT_DEFINITION
+    | INPUT_FIELD_DEFINITION
+    | ENUM_VALUE
+
+"""
+Use the specified name in the generated code instead of the GraphQL name.
+Use this for instance when the name would clash with a reserved keyword or field in the generated code.
+This directive is experimental.
+Since: 3.3.1
+"""
+directive @targetName(name: String!)
+on OBJECT
+    | INTERFACE
+    | ENUM
+    | ENUM_VALUE
+    | UNION
+    | SCALAR
+    | INPUT_OBJECT
 
-# Indicates how to compute a key from a field arguments.
-# `keyArgs` should contain a selection set. Composite args are not supported yet.
-directive @fieldPolicy(forField: String!, keyArgs: String!) repeatable on OBJECT
 
-# Indicates that the given field or enum value is still experimental and might be changed
-# in a backward incompatible manner
-directive @experimental(
-  reason: String! = "Experimental"
-) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+# @defer is not ratified yet in the GraphQL spec, but supported as an experimental feature in Apollo Kotlin
+# Taken from https://github.com/apollographql/apollo-kotlin/blob/05f2a3295517fb7a64c2259c38b453a37f3c4d19/libraries/apollo-ast/src/main/resources/builtins.graphqls#L136
 
+directive @defer(
+  label: String
+  if: Boolean! = true
+) on FRAGMENT_SPREAD | INLINE_FRAGMENT