From 211edbe0f10175a8d7a90da4e25efbecb06c28fe Mon Sep 17 00:00:00 2001 From: Dariusz Kuc Date: Fri, 25 Oct 2019 12:40:01 -0500 Subject: [PATCH] [docs] spring-server documentation updates --- docs/federated/federated-schemas.md | 7 ++-- docs/server/spring-auto-config.md | 6 +++ docs/server/spring-beans.md | 2 +- docs/server/spring-graphql-context.md | 59 +++++++++++++++++++++++++++ docs/server/spring-properties.md | 12 +++--- website/sidebars.json | 3 +- 6 files changed, 79 insertions(+), 10 deletions(-) create mode 100644 docs/server/spring-graphql-context.md diff --git a/docs/federated/federated-schemas.md b/docs/federated/federated-schemas.md index cbb0cba31d..8fa6e8ef88 100644 --- a/docs/federated/federated-schemas.md +++ b/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 { - override fun resolve(keys: Map): Product { - val id = keys["id"]?.toString()?.toIntOrNull() - // instantiate product using id + override suspend fun resolve(representations: List>): List = representations.map { keys -> + keys["id"]?.toString()?.toIntOrNull()?.let { id -> + Product(id) + } } } val federatedTypeRegistry = FederatedTypeRegistry(mapOf("Product" to productResolver)) diff --git a/docs/server/spring-auto-config.md b/docs/server/spring-auto-config.md index 286a82fde8..973626adbc 100644 --- a/docs/server/spring-auto-config.md +++ b/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 diff --git a/docs/server/spring-beans.md b/docs/server/spring-beans.md index c61797e75e..868d7c9917 100644 --- a/docs/server/spring-beans.md +++ b/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 diff --git a/docs/server/spring-graphql-context.md b/docs/server/spring-graphql-context.md new file mode 100644 index 0000000000..3cfa6617ec --- /dev/null +++ b/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 { + 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. diff --git a/docs/server/spring-properties.md b/docs/server/spring-properties.md index 5020f78169..69753b4f89 100644 --- a/docs/server/spring-properties.md +++ b/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 | diff --git a/website/sidebars.json b/website/sidebars.json index 8c33059bba..5aed7ca0e2 100644 --- a/website/sidebars.json +++ b/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"