[docs] spring-server documentation updates (#456)

Author: dariuszkuc

docs/federated/federated-schemas.md

@@ -96,9 +96,10 @@ data class Review(val reviewId: String, val text: String)
 
 // Generate the schema
 val productResolver = object: FederatedTypeResolver<Product> {
-    override fun resolve(keys: Map<String, Any>): Product {
-        val id = keys["id"]?.toString()?.toIntOrNull()
-        // instantiate product using id
+    override suspend fun resolve(representations: List<Map<String, Any>>): List<Product?> = representations.map { keys ->
+        keys["id"]?.toString()?.toIntOrNull()?.let { id ->
+            Product(id)
+	}
     }
 }
 val federatedTypeRegistry = FederatedTypeRegistry(mapOf("Product" to productResolver))

docs/server/spring-auto-config.md

@@ -58,3 +58,9 @@ type Widget {
   value: String!
 }
 ```
+
+Newly created GraphQL server starts up with following preconfigured default routes:
+
+* **/graphql** - GraphQL server endpoint used for processing queries and mutations
+* **/sdl** - convenience endpoint that returns current schema in Schema Definition Language format
+* **/playground** - Prisma Labs GraphQL Playground IDE endpoint

docs/server/spring-beans.md

@@ -3,7 +3,7 @@ id: spring-beans
 title: Automatically Created Beans
 ---
 
-`graphql-kotlin-spring-server` automatically creates all required beans to start GraphQL web server. Many of the beans are conditionally created and default behavior
+`graphql-kotlin-spring-server` automatically creates all the necessary beans to start GraphQL web server. Many of the beans are conditionally created and default behavior
 can be customized by providing custom beans in your application context. See sections below for the information about all automatically created beans.
 
 ## Schema Generation

docs/server/spring-graphql-context.md

@@ -0,0 +1,59 @@
+---
+id: spring-graphql-context
+title: Generating GraphQL Context
+---
+
+`graphql-kotlin-spring-server` provides a simple mechanism to build [GraphQL context](../execution/contextual-data) per query execution through
+[GraphQLContextFactory](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/GraphQLContextFactory.kt).
+Once context factory bean is available in the Spring application context it will then be used in a corresponding
+[ContextWebFilter](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/ContextWebFilter.kt)
+to populate GraphQL context based on the incoming request and make it available during query execution.
+
+For example if we define our custom context as follows:
+
+```kotlin
+data class MyGraphQLContext(val myCustomValue: String)
+```
+
+We can generate corresponding `GraphQLContextFactory` bean:
+
+```kotlin
+@Component
+class MyGraphQLContextFactory: GraphQLContextFactory<MyGraphQLContext> {
+    override suspend fun generateContext(
+        request: ServerHttpRequest, 
+        response: ServerHttpResponse
+    ): MyGraphQLContext = MyGraphQLContext(
+        myCustomValue = request.headers.getFirst("MyHeader") ?: "defaultContext"
+    )
+}
+```
+
+Once your application is configured to build your custom `MyGraphQLContext`, we can then specify it as function argument by annotating it with `@GraphQLContext`. 
+While executing the query, the corresponding GraphQL context will be read from the environment and automatically injected to the function input arguments.
+
+```kotlin
+@Component
+class ContextualQuery: Query {
+    fun contextualQuery(
+        value: Int,
+        @GraphQLContext context: MyGraphQLContext
+    ): ContextualResponse = ContextualResponse(value, context.myCustomValue)
+}
+```
+
+The above query would produce the following GraphQL schema:
+
+```graphql
+schema {
+  query: Query
+}
+
+type Query {
+  contextualQuery(
+    value: Int!
+  ): ContextualResponse!
+}
+```
+
+Notice that the `@GraphQLContext` annotated argument is not reflected in the generated GraphQL schema.

docs/server/spring-properties.md

@@ -5,15 +5,17 @@ title: Configuration Properties
 
 `graphql-kotlin-spring-server` relies on [GraphQLConfigurationProperties](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/GraphQLConfigurationProperties.kt) 
 to provide various customizations of the auto-configuration library. All applicable configuration properties expose [configuration
-metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html) that provides
+metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html) that provide
 details on the supported configuration properties.
 
 | Property | Description | Default Value |
 |----------|-------------|---------------|
-| graphql.endpoint | GraphQL server endpoint | "graphql" |
+| graphql.endpoint | GraphQL server endpoint | graphql |
 | graphql.packages | List of supported packages that can contain GraphQL schema type definitions | |
 | graphql.federation.enabled | Boolean flag indicating whether to generate federated GraphQL model | false |
-| graphql.subscriptions.endpoint | GraphQL subscriptions endpoint | "subscriptions" |
-| graphql.subscriptions.keepAliveInterval | Keep the websocket alive and send a message to the client every interval in ms. Defaults to not sending messages | null |
 | graphql.playground.enabled | Boolean flag indicating whether to enabled Prisma Labs Playground GraphQL IDE | true |
-| graphql.playground.endpoint | Prisma Labs Playground GraphQL IDE endpoint | "playground" |
+| graphql.playground.endpoint | Prisma Labs Playground GraphQL IDE endpoint | playground |
+| graphql.sdl.enabled | Boolean flag indicating whether to expose SDL endpoint | true |
+| graphql.sdl.endpoint | GraphQL SDL endpoint | sdl |
+| graphql.subscriptions.endpoint | GraphQL subscriptions endpoint | subscriptions |
+| graphql.subscriptions.keepAliveInterval | Keep the websocket alive and send a message to the client every interval in ms. Defaults to not sending messages | null |

website/sidebars.json

@@ -53,7 +53,8 @@
     "Server": [
       "server/spring-auto-config",
       "server/spring-beans",
-      "server/spring-properties"
+      "server/spring-properties",
+      "server/spring-graphql-context"
     ],
     "Contributors": [
       "contributors/release-proc"