[docs] update federation docs with more detail (ExpediaGroup#455)

Author: dariuszkuc

docs/federated/apollo-federation.md

@@ -0,0 +1,17 @@
+---
+id: apollo-federation
+title: Apollo Federation
+---
+
+In many cases, exposing single GraphQL API that exposes unified view of all the available data provides tremendous value
+to their clients. As the underlying graph scales, managing single monolithic GraphQL server might become less and less
+feasible making it much harder to manage and leading to unnecessary bottlenecks. Migrating towards federated model with
+an API gateway and a number of smaller GraphQL services behind it alleviates some of those problems and allows teams to
+scale their graphs more easily.
+
+[Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) is an architecture for 
+composing multiple GraphQL services into a single graph. Federated schemas rely on a number of custom directives to 
+instrument the behavior of the underlying graph and convey the relationships between different schema types. Each individual 
+GraphQL server generates a valid GraphQL schema and can be run independently. This is in contrast with traditional schema 
+stitching approach where relationships between individual services, i.e. linking configuration, is configured at the GraphQL 
+Gateway level.

docs/federated/federated-schemas.md

@@ -2,25 +2,19 @@
 id: federated-schemas 
 title: Federated Schemas
 ---
-In many cases, exposing single GraphQL API that exposes unified view of all the available data provides tremendous value
-to their clients. As the underlying graph scales, managing single monolithic GraphQL server might become less and less
-feasible making it much harder to manage and leading to unnecessary bottlenecks. Migrating towards federated model with
-an API gateway and a number of smaller GraphQL services behind it alleviates some of those problems and allows teams to
-scale their graphs more easily.
-
-## Apollo Federation
-
-[Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) is an architecture for
-composing multiple GraphQL services into a single graph. Each individual GraphQL server generates valid GraphQL schema
-and can be developed and run independently.
-
-`graphql-kotlin-federation` extends the functionality of `graphql-kotlin-schema-generator` and allows you to easily
-generate federated GraphQL schemas directly from the code. Federated schemas rely on a number of [new directives](federated-directives) to
-instrument the behavior of the underlying graph. Once all the federated objects are annotated, you will also have to configure corresponding
-FederatedTypeResolvers that are used to instantiate underlying federated objects and finally generate the schema using
-`toFederatedSchema` function
+
+`graphql-kotlin-federation` library extends the functionality of the `graphql-kotlin-schema-generator` and allows you to 
+easily generate federated GraphQL schemas directly from the code. Federated schema is generated by calling 
+`toFederatedSchema` function that accepts federated configuration as well as a list of regular queries, mutations and 
+subscriptions exposed by the schema.
+
+All [federated directives]((federated-directives)) are provided as annotations that are used to decorate your classes, 
+properties and functions. Since federated types might not be accessible through the regular query execution path, they 
+are explicitly picked up by the schema generator based on their directives. Due to the above, we also need to provide
+a way to instantiate the underlying federated objects by implementing corresponding `FederatedTypeResolvers`. See 
+[type resolution wiki](type-resolution) for more details on how federated types are resolved. Final federated schema
+is then generated by invoking the `toFederatedSchema` function
 ([link](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/federation/toFederatedSchema.kt#L34)).
-See [type resolution](type-resolution) for more details on how federated types are resolved.
 
 **In order to generate valid federated schemas, you will need to annotate both your base schema and the one extending
 it**. Federated Gateway (e.g. Apollo) will then combine the individual graphs to form single federated graph.
@@ -32,7 +26,8 @@ it**. Federated Gateway (e.g. Apollo) will then combine the individual graphs to
 
 Base schema defines GraphQL types that will be extended by schemas exposed by other GraphQL services. In the example
 below, we define base `Product` type with `id` and `description` fields. `id` is the primary key that uniquely
-identifies the `Product` type object and is specified in `@key` directive.
+identifies the `Product` type object and is specified in `@key` directive. Since it is a base schema that doesn't expose 
+any extended functionality our FederatedTypeRegistry does not include any federated resolvers.
 
 ```kotlin
 @KeyDirective(fields = FieldSet("id"))
@@ -52,7 +47,7 @@ val queries = listOf(TopLevelObject(ProductQuery()))
 toFederatedSchema(config, queries)
 ```
 
-Generates the following schema with additional federated types
+Example above generates the following schema with additional federated types:
 
 ```graphql
 schema {
@@ -83,7 +78,9 @@ Extended federated GraphQL schemas provide additional functionality to the types
 services. In the example below, `Product` type is extended to add new `reviews` field to it. Primary key needed to
 instantiate the `Product` type (i.e. `id`) has to match the `@key` definition on the base type. Since primary keys are
 defined on the base type and are only referenced from the extended type, all of the fields that are part of the field
-set specified in `@key` directive have to be marked as `@external`.
+set specified in `@key` directive have to be marked as `@external`. Finally, we also need to specify an "entry point" 
+for the federated type - we need to create a FederatedTypeResolver that will be used to instantiate the federated 
+`Product` type when processing federated queries.
 
 ```kotlin
 @KeyDirective(fields = FieldSet("id"))
@@ -110,7 +107,7 @@ val config = FederatedSchemaGeneratorConfig(supportedPackages = listOf("org.exam
 toFederatedSchema(config)
 ```
 
-Generates the following federated schema
+Our extended schema will then be generated as:
 
 ```graphql
 schema {
@@ -141,7 +138,8 @@ type _Service {
 
 #### Federated GraphQL schema
 
-Federated Gateway will then combine the schemas from the individual services to generate single schema.
+Once we have both base and extended GraphQL services up and running, we will also need to configure Federated Gateway 
+to combine them into a single schema. Using the examples above, our final federated schema will be generated as:
 
 ```graphql
 schema {
@@ -163,3 +161,5 @@ type Query {
   product(id: String!): Product!
 }
 ```
+
+See our [federation example](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation) for additional details.

website/sidebars.json

@@ -45,6 +45,7 @@
       }
     ],
     "Federation": [
+      "federated/apollo-federation",
       "federated/federated-schemas",
       "federated/federated-directives",
       "federated/type-resolution"