docs: update spring server documentation to match latest code (#424)

* docs: update spring server documentation to match latest code * Apply suggestions from code review Co-Authored-By: Saurav Tapader <tapaderster@gmail.com>
ExpediaGroup · Oct 11, 2019 · 9816f5c · 9816f5c
1 parent 403df62
commit 9816f5c
Show file tree

Hide file tree

Showing 5 changed files with 132 additions and 121 deletions.
diff --git a/docs/server/spring-auto-config.md b/docs/server/spring-auto-config.md
@@ -0,0 +1,60 @@
+---
+id: spring-auto-config
+title: Spring Boot Auto Configuration
+---
+
+[graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server)
+is a Spring Boot auto-configuration library that automatically configures beans required to start up a reactive GraphQL
+web server.
+
+At a minimum, in order for `graphql-kotlin-spring-server` to automatically configure your GraphQL web server you need to
+specify a list of supported packages that can be scanned for exposing your schema objects through reflections.
+
+You can do this through the spring application config or by overriding the `SchemaGeneratorConfig` bean. See customization below.
+
+```yaml
+graphql:
+  packages:
+    - "com.your.package"
+```
+
+
+In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement
+corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server`
+auto-configuration library.
+
+```kotlin
+@Component
+class MyAwesomeQuery : Query {
+  fun myAwesomeQuery(): Widget { ... }
+}
+
+@Component
+class MyAwesomeMutation : Mutation {
+  fun myAwesomeMutation(widget: Widget): Widget { ... }
+}
+
+data class Widget(val id: Int, val value: String)
+```
+
+will result in a Spring Boot reactive GraphQL web application with following schema.
+
+```graphql
+schema {
+  query: Query
+  mutation: Mutation
+}
+
+type Query {
+  myAwesomeQuery(): Widget!
+}
+
+type Mutation {
+  myAwesomeMutation(widget: Widget!): Widget!
+}
+
+type Widget {
+  id: Int!
+  value: String!
+}
+```
diff --git a/docs/server/spring.md → docs/server/spring-beans.md b/docs/server/spring.md → docs/server/spring-beans.md
@@ -1,100 +1,49 @@
----
-id: spring
-title: Spring
----
-[graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server)
-is a Spring Boot auto-configuration library that automatically configures beans required to start up reactive GraphQL
-web server.
-
-At a minimum, in order for `graphql-kotlin-spring-server` to automatically configure your GraphQL web server you need to
-specify list of supported packages that can be scanned for exposing your schema objects through reflections.
-
-You can do this through the spring application config or by overriding the `SchemaGeneratorConfig` bean. See customization below.
-
-```yaml
-graphql:
-  packages:
-    - "com.your.package"
-```
-
-
-In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement
-corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server`
-auto-configuration library.
-
-```kotlin
-class MyAwesomeQuery : Query {
-  fun myAwesomeQuery(): Widget { ... }
-}
-
-class MyAwesomeMutation : Mutation {
-  fun myAwesomeMutation(widget: Widget): Widget { ... }
-}
-
-data class Widget(val id: Int, val value: String)
-```
-
-will result in a Spring Boot reactive GraphQL web application with following schema.
-
-```graphql
-schema {
-  query: Query
-  mutation: Mutation
-}
-
-type Query {
-  myAwesomeQuery(): Widget!
-}
-
-type Mutation {
-  myAwesomeMutation(widget: Widget!): Widget!
-}
-
-type Widget {
-  id: Int!
-  value: String!
-}
-```
-
-## Customization
-
-All beans created by `graphql-kotlin-spring-server` are conditionally created. If any of the target beans are created in
-the application context, auto-configuration will back off.
-
-Conditionally generated beans:
-
-* **SchemaGeneratorConfig** - schema generation configuration information, see
-  [Spring Configuration](spring-config) for details. _You should
-  register custom configuration bean if you want to specify custom schema generator hooks._
-* **FederatedTypeRegistry** - default type registry without any resolvers, created only if generating federated GraphQL
-  schema. _You should register your custom type registry bean whenever implementing federated GraphQL schema with
-  extended types_.
-* **GraphQLSchema** - GraphQL schema generated based on the schema generator configuration and  `Query`, `Mutation` and
-  `Subscription` objects available in the application context
-* **DataFetcherExceptionHandler** - GraphQL exception handler used from the various execution strategies, defaults to
-  [KotlinDataFetcherExceptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/exception/KotlinDataFetcherExceptionHandler.kt)
-
-* **GraphQL** - `graphql-java` GraphQL query execution engine generated using `GraphQLSchema` with default async
-  execution strategies. GraphQL engine can be customized by optionally providing
-  [Instrumentation](https://www.graphql-java.com/documentation/v13/instrumentation/),
-  [ExecutionIdProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/ExecutionIdProvider.java)
-  and
-  [PreparsedDocumentProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/preparsed/PreparsedDocumentProvider.java)
-  in the application context.
-* **QueryHandler** - handler invoked from GraphQL query route that executes the incoming request, defaults to
-  [SimpleQueryHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/QueryHandler.kt)
-* **GraphQLContextFactory** - factory used by context WebFilter to generate GraphQL context based on the incoming
-  request. GraphQL context can be any object. Defaults to empty
-  [GraphQLContext](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/GraphQLContext.java)
-* **SubscriptionHandler** - Web socket handler for executing GraphQL subscriptions, defaults to
-  [SimpleSubscriptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionHandler.kt#L49),
-  created only if `Subscription` bean is available in the context
-* **WebSocketHandlerAdapter** - [see Spring
-  documentation](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/socket/server/support/WebSocketHandlerAdapter.html),
-  created only if `Subscription` bean is available in the context
-
-The following beans are currently automatically created and cannot be disabled:
-
-* Web filter for generating and populating GraphQL context
-* Default routes for GraphQL queries/mutations and SDL endpoint
-* Default subscription handler mapping, created only if `Subscription` bean is available in the context
+---
+id: spring-beans
+title: Automatically Created Beans
+---
+
+All beans created by `graphql-kotlin-spring-server` are conditionally created. If any of the target beans are created in
+the application context, auto-configuration will back off.
+
+Conditionally generated beans:
+
+* **SchemaGeneratorConfig/FederatedSchemaGeneratorConfig** - schema generation configuration information, see
+  [Spring Configuration](spring-config) for details. _You should
+  register custom configuration bean if you want to specify custom schema generator hooks._
+* **FederatedTypeRegistry** - default type registry without any resolvers, created only if generating federated GraphQL
+  schema. _You should register your custom type registry bean whenever implementing federated GraphQL schema with
+  extended types_.
+* **GraphQLSchema** - GraphQL schema generated based on the schema generator configuration and  `Query`, `Mutation` and
+  `Subscription` objects available in the application context
+* **DataFetcherExceptionHandler** - GraphQL exception handler used from the various execution strategies, defaults to
+  [KotlinDataFetcherExceptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/exception/KotlinDataFetcherExceptionHandler.kt)
+* **GraphQL** - `graphql-java` GraphQL query execution engine generated using `GraphQLSchema` with default async
+  execution strategies. GraphQL engine can be customized by optionally providing a list of 
+  [Instrumentation](https://www.graphql-java.com/documentation/v13/instrumentation/) beans (which can be ordered by implementing Spring
+  Ordered interface), [ExecutionIdProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/ExecutionIdProvider.java)
+  and
+  [PreparsedDocumentProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/preparsed/PreparsedDocumentProvider.java)
+  in the application context.
+* **DataLoaderRegistryFactory** - factory used to create DataLoaderRegistry instance per query execution. See [graphql-java documentation](https://www.graphql-java.com/documentation/v13/batching/) 
+  for more details
+* **QueryHandler** - handler invoked from GraphQL query route that executes the incoming request, defaults to
+  [SimpleQueryHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/QueryHandler.kt)
+* **GraphQLContextFactory** - factory used by context WebFilter to generate GraphQL context based on the incoming
+  request. GraphQL context can be any object. Defaults to empty
+  [GraphQLContext](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/GraphQLContext.java)
+* **SubscriptionHandler** - Web socket handler for executing GraphQL subscriptions, defaults to
+  [SimpleSubscriptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionHandler.kt#L49),
+  created only if `Subscription` bean is available in the context
+* **WebSocketHandlerAdapter** - [see Spring
+  documentation](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/socket/server/support/WebSocketHandlerAdapter.html),
+  created only if `Subscription` bean is available in the context
+
+The following beans are currently automatically created and cannot be disabled:
+
+* Web filter for generating and populating GraphQL context
+* Default routes for GraphQL queries/mutations and SDL endpoint
+* Default route for Prisma Labs Playground, created only if playground is enabled
+* Default `ApolloSubscriptionProtocolHandler` for handling GraphQL subscriptions, created only if `Subscription` bean is available in the context
+* Default `SubscriptionWebSocketHandler` that utilizes above subscription protocol handler, created only if `Subscription` bean is available in the context
+* Default subscription handler mapping, created only if `Subscription` bean is available in the context
diff --git a/docs/server/spring-config.md b/docs/server/spring-config.md
diff --git a/docs/server/spring-properties.md b/docs/server/spring-properties.md
@@ -0,0 +1,19 @@
+---
+id: spring-properties
+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
+details on the supported configuration properties.
+
+| Property | Description | Default Value |
+|----------|-------------|---------------|
+| 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 | |
+| 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 | |
+| graphql.playground.endpoint | Prisma Labs Playground GraphQL IDE endpoint | "playground" |
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -39,9 +39,10 @@
       "federated/federated-directives",
       "federated/type-resolution"
     ],
-    "Spring Server": [
-      "server/spring",
-      "server/spring-config"
+    "Server": [
+      "server/spring-auto-config",
+      "server/spring-beans",
+      "server/spring-properties"
     ],
     "Contributors": [
       "contributors/release-proc"