[federation] fix @link definition and doc cleanup (#1588)

Fixed `@link` directive definition from:

```graphql
directive @link(url: String, import: [Import]) repeatable on SCHEMA
```

to

```graphql
directive @link(url: String!, import: [Import]) repeatable on SCHEMA
```

Cleaned up some federation docs as well.

Author: dariuszkuc

examples/client/src/integration/wiremock/__files/schema.graphql

@@ -1,4 +1,4 @@
-schema @link(url : "https://specs.apollo.dev/link/v1.0/") @link(import : ["extends", "external", "inaccessible", "key", "link", "override", "provides", "requires", "shareable", "tag", "_FieldSet"], url : "https://www.apollographql.com/docs/federation/federation-spec/"){
+schema @link(import : ["extends", "external", "inaccessible", "key", "link", "override", "provides", "requires", "shareable", "tag", "_FieldSet"], url : "https://www.apollographql.com/docs/federation/federation-spec/"){
     query: Query
     mutation: Mutation
 }
@@ -28,7 +28,7 @@ directive @include(
 directive @key(fields: _FieldSet!, resolvable: Boolean) repeatable on OBJECT | INTERFACE
 
 "Links definitions within the document to external schemas."
-directive @link(import: [String], url: String) repeatable on SCHEMA
+directive @link(import: [String], url: String!) repeatable on SCHEMA
 
 "Overrides fields resolution logic from other subgraph. Used for migrating fields from one subgraph to another."
 directive @override(from: String!) repeatable on FIELD_DEFINITION

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/ExtendsDirective.kt

@@ -20,6 +20,9 @@ import com.expediagroup.graphql.generator.annotations.GraphQLDirective
 import graphql.introspection.Introspection.DirectiveLocation
 
 /**
+ * **`@extends` directive is deprecated**. Federation v2 no longer requires `@extends` directive due to the smart entity type
+ * merging. All usage of `@extends` directive should be removed from your Federation v2 schemas.
+ *
  * ```graphql
  * directive @extends on OBJECT | INTERFACE
  * ```

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/ExternalDirective.kt

@@ -27,25 +27,29 @@ import graphql.introspection.Introspection.DirectiveLocation
  * The @external directive is used to mark a field as owned by another service. This allows service A to use fields from service B while also knowing at runtime the types of that field. @external
  * directive is only applicable on federated extended types. All the external fields should either be referenced from the @key, @requires or @provides directives field sets.
  *
- * Due to the smart merging of entity types, `@external` directive is no longer required on `@key` fields and can be omitted from the schema. `@external` directive is only required on fields
- * referenced by the `@requires` and `@provides` directive.
+ * Due to the smart merging of entity types, Federation v2 no longer requires `@external` directive on `@key` fields and can be safely omitted from the schema. `@external` directive is only required
+ * on fields referenced by the `@requires` and `@provides` directive.
  *
  * Example:
  * Given
  *
  * ```kotlin
  * @KeyDirective(FieldSet("id"))
- * @ExtendsDirective
- * class Product(@ExternalDirective val id: String) {
- *   fun newFunctionality(): String = "whatever"
+ * class Product(val id: String) {
+ *   @ExternalDirective
+ *   var externalField: String by Delegates.notNull()
+ *
+ *   @RequiresDirective(FieldSet("externalField"))
+ *   fun newFunctionality(): String { ... }
  * }
  * ```
  *
  * should generate
  *
  * ```graphql
- * type Product @extends @key(fields : "id") {
- *   id: String! @external
+ * type Product @key(fields : "id") {
+ *   externalField: String! @external
+ *   id: String!
  *   newFunctionality: String!
  * }
  * ```

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/InaccessibleDirective.kt

@@ -33,7 +33,9 @@ import graphql.introspection.Introspection.DirectiveLocation
  *     | ARGUMENT_DEFINITION
  * ```
  *
- * Inaccessible directive marks location within schema as inaccessible from the GraphQL Gateway. This allows you to incrementally add schema elements (e.g. fields) to multiple subgraphs without breaking composition.
+ * Inaccessible directive marks location within schema as inaccessible from the GraphQL Gateway. While `@inaccessible` fields are not exposed by the gateway to the clients, they are still available for
+ * query plans and can be referenced from `@key` and `@requires` directives. This allows you to not expose sensitive fields to your clients but still make them available for computations. Inaccessible
+ * can also be used to incrementally add schema elements (e.g. fields) to multiple subgraphs without breaking composition.
  *
  * > NOTE: Location within schema will be inaccessible from the GraphQL Gateway as long as **any** of the subgraphs marks that location as `@inacessible`.
  *

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/KeyDirective.kt

@@ -31,9 +31,11 @@ import graphql.schema.GraphQLArgument
  * directive @key(fields: _FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
  * ```
  *
- * The @key directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object or interface. Key directive should be specified on the root entity type as
- * well as all the corresponding federated (i.e. extended) types. Key fields specified in the directive field set should correspond to a valid field on the underlying GraphQL interface/object.
- * Federated extended types should also instrument all the referenced key fields with @external directive.
+ * The `@key` directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object or interface. The specified field set can represent single field (e.g. `"id"`),
+ * multiple fields (e.g. `"id name"`) or nested selection sets (e.g. `"id user { name }"`). Multiple keys can be specified on a target type.
+ *
+ * Key directives should be specified on all entities (objects that can resolve its fields across multiple subgraphs). Key fields specified in the directive field set should correspond to a valid field
+ * on the underlying GraphQL interface/object.
  *
  * Example:
  * Given following entity type definition

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/LinkDirective.kt

@@ -21,13 +21,14 @@ import graphql.Scalars
 import graphql.introspection.Introspection.DirectiveLocation
 import graphql.schema.GraphQLArgument
 import graphql.schema.GraphQLList
+import graphql.schema.GraphQLNonNull
 
 const val LINK_SPEC_URL = "https://specs.apollo.dev/link/v1.0/"
 const val FEDERATION_SPEC_URL = "https://specs.apollo.dev/federation/v2.0"
 
 /**
  * ```graphql
- * directive @link(url: String, import: [Import]) repeatable on SCHEMA
+ * directive @link(url: String!, import: [Import]) repeatable on SCHEMA
  * ```
  *
  * The `@link` directive links definitions within the document to external schemas.
@@ -62,7 +63,7 @@ internal val LINK_DIRECTIVE_TYPE: graphql.schema.GraphQLDirective = graphql.sche
     .argument(
         GraphQLArgument.newArgument()
             .name("url")
-            .type(Scalars.GraphQLString)
+            .type(GraphQLNonNull.nonNull(Scalars.GraphQLString))
     )
     .argument(
         GraphQLArgument

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/ProvidesDirective.kt

@@ -25,14 +25,15 @@ import graphql.introspection.Introspection.DirectiveLocation
  * directive @provides(fields: _FieldSet!) on FIELD_DEFINITION
  * ```
  *
- * The @provides directive is used to annotate the expected returned fieldset from a field on a base type that is guaranteed to be selectable by the gateway. This allows you to expose only a subset
- * of fields from the underlying federated object type to be selectable from the federated schema without the need to call other subgraphs. Provided fields specified in the directive field set should
- * correspond to a valid field on the underlying GraphQL interface/object type. @provides directive can only be used on fields returning federated extended objects.
+ * The `@provides` directive is a router optimization hint specifying field set that can be resolved locally at the given subgraph through this particular query path. This allows you to expose only a
+ * subset of fields from the underlying entity type to be selectable from the federated schema without the need to call other subgraphs. Provided fields specified in the directive field set should
+ * correspond to a valid field on the underlying GraphQL interface/object type. `@provides` directive can only be used on fields returning entities.
+ *
+ * >NOTE: Federation v2 does not require `@provides` directive if field can **always** be resolved locally. `@provides` should be omitted in this situation.
  *
  * Example 1:
  * We might want to expose only name of the user that submitted a review.
  *
- * >NOTE: Due to the smart entity type merging, Federation v2 does not require `@provides` directive if field can always be resolved locally.
  *
  * ```kotlin
  * @KeyDirective(FieldSet("id"))

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/RequiresDirective.kt

@@ -25,16 +25,15 @@ import graphql.introspection.Introspection.DirectiveLocation
  * directive @requires(fields: _FieldSet!) on FIELD_DEFINITON
  * ```
  *
- * The @requires directive is used to annotate the required input field set from a base type for a resolver. It is used to develop a query plan where the required fields may not be needed by the
- * client, but the service may need additional information from other services. Required fields specified in the directive field set should correspond to a valid field on the underlying GraphQL
- * interface/object and should be instrumented with @external directive. Since @requires directive specifies additional fields (besides the one specified in @key directive) that are required to
- * resolve federated type fields, this directive can only be specified on federated extended objects fields.
+ * The `@requires` directive is used to specify external (provided by other subgraphs) entity fields that are needed to resolve target field. It is used to develop a query plan where
+ * the required fields may not be needed by the client, but the service may need additional information from other subgraphs. Required fields specified in the directive field set should
+ * correspond to a valid field on the underlying GraphQL interface/object and should be instrumented with `@external` directive.
  *
- * NOTE: fields specified in the @requires directive will only be specified in the queries that reference those fields. This is problematic for Kotlin as the non nullable primitive properties have
- * to be initialized when they are declared. Simplest workaround for this problem is to initialize the underlying property to some dummy value that will be used if it is not specified. This approach
- * might become problematic though as it might be impossible to determine whether fields was initialized with the default value or the invalid/default value was provided by the federated query.
- * Another potential workaround is to rely on delegation to initialize the property after the object gets created. This will ensure that exception will be thrown if queries attempt to resolve fields
- * that reference the uninitialized property.
+ * Fields specified in the `@requires` directive will only be specified in the queries that reference those fields. This is problematic for Kotlin as the non-nullable primitive properties
+ * have to be initialized when they are declared. Simplest workaround for this problem is to initialize the underlying property to some default value (e.g. null) that will be used if
+ * it is not specified. This approach might become problematic though as it might be impossible to determine whether fields was initialized with the default value or the invalid/default
+ * value was provided by the federated query. Another potential workaround is to rely on delegation to initialize the property after the object gets created. This will ensure that exception
+ * will be thrown if queries attempt to resolve fields that reference the uninitialized property.
  *
  * Example:
  * Given

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/FederatedSchemaV2GeneratorTest.kt

@@ -61,7 +61,7 @@ class FederatedSchemaV2GeneratorTest {
             directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 
             "Links definitions within the document to external schemas."
-            directive @link(import: [String], url: String) repeatable on SCHEMA
+            directive @link(import: [String], url: String!) repeatable on SCHEMA
 
             "Overrides fields resolution logic from other subgraph. Used for migrating fields from one subgraph to another."
             directive @override(from: String!) on FIELD_DEFINITION

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/execution/ServiceQueryResolverTest.kt

@@ -103,7 +103,7 @@ directive @inaccessible on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINIT
 directive @key(fields: FieldSet!) repeatable on OBJECT | INTERFACE
 
 "Links definitions within the document to external schemas."
-directive @link(import: [String], url: String) repeatable on SCHEMA
+directive @link(import: [String], url: String!) repeatable on SCHEMA
 
 "Overrides fields resolution logic from other subgraph. Used for migrating fields from one subgraph to another."
 directive @override(from: String!) on FIELD_DEFINITION
@@ -161,7 +161,7 @@ directive @inaccessible on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINIT
 directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 
 "Links definitions within the document to external schemas."
-directive @link(import: [String], url: String) repeatable on SCHEMA
+directive @link(import: [String], url: String!) repeatable on SCHEMA
 
 "Overrides fields resolution logic from other subgraph. Used for migrating fields from one subgraph to another."
 directive @override(from: String!) on FIELD_DEFINITION