Skip to content

Commit 9816f5c

Browse files
dariuszkuctapaderster
dariuszkuc
and
tapaderster
authored
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 <[email protected]>
1 parent 403df62 commit 9816f5c

File tree

5 files changed

+132
-121
lines changed

5 files changed

+132
-121
lines changed

‎docs/server/spring-auto-config.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: spring-auto-config
3+
title: Spring Boot Auto Configuration
4+
---
5+
6+
[graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server)
7+
is a Spring Boot auto-configuration library that automatically configures beans required to start up a reactive GraphQL
8+
web server.
9+
10+
At a minimum, in order for `graphql-kotlin-spring-server` to automatically configure your GraphQL web server you need to
11+
specify a list of supported packages that can be scanned for exposing your schema objects through reflections.
12+
13+
You can do this through the spring application config or by overriding the `SchemaGeneratorConfig` bean. See customization below.
14+
15+
```yaml
16+
graphql:
17+
packages:
18+
- "com.your.package"
19+
```
20+
21+
22+
In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement
23+
corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server`
24+
auto-configuration library.
25+
26+
```kotlin
27+
@Component
28+
class MyAwesomeQuery : Query {
29+
fun myAwesomeQuery(): Widget { ... }
30+
}
31+
32+
@Component
33+
class MyAwesomeMutation : Mutation {
34+
fun myAwesomeMutation(widget: Widget): Widget { ... }
35+
}
36+
37+
data class Widget(val id: Int, val value: String)
38+
```
39+
40+
will result in a Spring Boot reactive GraphQL web application with following schema.
41+
42+
```graphql
43+
schema {
44+
query: Query
45+
mutation: Mutation
46+
}
47+
48+
type Query {
49+
myAwesomeQuery(): Widget!
50+
}
51+
52+
type Mutation {
53+
myAwesomeMutation(widget: Widget!): Widget!
54+
}
55+
56+
type Widget {
57+
id: Int!
58+
value: String!
59+
}
60+
```

‎docs/server/spring.md renamed to ‎docs/server/spring-beans.md

Lines changed: 49 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,49 @@
1-
---
2-
id: spring
3-
title: Spring
4-
---
5-
[graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server)
6-
is a Spring Boot auto-configuration library that automatically configures beans required to start up reactive GraphQL
7-
web server.
8-
9-
At a minimum, in order for `graphql-kotlin-spring-server` to automatically configure your GraphQL web server you need to
10-
specify list of supported packages that can be scanned for exposing your schema objects through reflections.
11-
12-
You can do this through the spring application config or by overriding the `SchemaGeneratorConfig` bean. See customization below.
13-
14-
```yaml
15-
graphql:
16-
packages:
17-
- "com.your.package"
18-
```
19-
20-
21-
In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement
22-
corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server`
23-
auto-configuration library.
24-
25-
```kotlin
26-
class MyAwesomeQuery : Query {
27-
fun myAwesomeQuery(): Widget { ... }
28-
}
29-
30-
class MyAwesomeMutation : Mutation {
31-
fun myAwesomeMutation(widget: Widget): Widget { ... }
32-
}
33-
34-
data class Widget(val id: Int, val value: String)
35-
```
36-
37-
will result in a Spring Boot reactive GraphQL web application with following schema.
38-
39-
```graphql
40-
schema {
41-
query: Query
42-
mutation: Mutation
43-
}
44-
45-
type Query {
46-
myAwesomeQuery(): Widget!
47-
}
48-
49-
type Mutation {
50-
myAwesomeMutation(widget: Widget!): Widget!
51-
}
52-
53-
type Widget {
54-
id: Int!
55-
value: String!
56-
}
57-
```
58-
59-
## Customization
60-
61-
All beans created by `graphql-kotlin-spring-server` are conditionally created. If any of the target beans are created in
62-
the application context, auto-configuration will back off.
63-
64-
Conditionally generated beans:
65-
66-
* **SchemaGeneratorConfig** - schema generation configuration information, see
67-
[Spring Configuration](spring-config) for details. _You should
68-
register custom configuration bean if you want to specify custom schema generator hooks._
69-
* **FederatedTypeRegistry** - default type registry without any resolvers, created only if generating federated GraphQL
70-
schema. _You should register your custom type registry bean whenever implementing federated GraphQL schema with
71-
extended types_.
72-
* **GraphQLSchema** - GraphQL schema generated based on the schema generator configuration and `Query`, `Mutation` and
73-
`Subscription` objects available in the application context
74-
* **DataFetcherExceptionHandler** - GraphQL exception handler used from the various execution strategies, defaults to
75-
[KotlinDataFetcherExceptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/exception/KotlinDataFetcherExceptionHandler.kt)
76-
77-
* **GraphQL** - `graphql-java` GraphQL query execution engine generated using `GraphQLSchema` with default async
78-
execution strategies. GraphQL engine can be customized by optionally providing
79-
[Instrumentation](https://www.graphql-java.com/documentation/v13/instrumentation/),
80-
[ExecutionIdProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/ExecutionIdProvider.java)
81-
and
82-
[PreparsedDocumentProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/preparsed/PreparsedDocumentProvider.java)
83-
in the application context.
84-
* **QueryHandler** - handler invoked from GraphQL query route that executes the incoming request, defaults to
85-
[SimpleQueryHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/QueryHandler.kt)
86-
* **GraphQLContextFactory** - factory used by context WebFilter to generate GraphQL context based on the incoming
87-
request. GraphQL context can be any object. Defaults to empty
88-
[GraphQLContext](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/GraphQLContext.java)
89-
* **SubscriptionHandler** - Web socket handler for executing GraphQL subscriptions, defaults to
90-
[SimpleSubscriptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionHandler.kt#L49),
91-
created only if `Subscription` bean is available in the context
92-
* **WebSocketHandlerAdapter** - [see Spring
93-
documentation](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/socket/server/support/WebSocketHandlerAdapter.html),
94-
created only if `Subscription` bean is available in the context
95-
96-
The following beans are currently automatically created and cannot be disabled:
97-
98-
* Web filter for generating and populating GraphQL context
99-
* Default routes for GraphQL queries/mutations and SDL endpoint
100-
* Default subscription handler mapping, created only if `Subscription` bean is available in the context
1+
---
2+
id: spring-beans
3+
title: Automatically Created Beans
4+
---
5+
6+
All beans created by `graphql-kotlin-spring-server` are conditionally created. If any of the target beans are created in
7+
the application context, auto-configuration will back off.
8+
9+
Conditionally generated beans:
10+
11+
* **SchemaGeneratorConfig/FederatedSchemaGeneratorConfig** - schema generation configuration information, see
12+
[Spring Configuration](spring-config) for details. _You should
13+
register custom configuration bean if you want to specify custom schema generator hooks._
14+
* **FederatedTypeRegistry** - default type registry without any resolvers, created only if generating federated GraphQL
15+
schema. _You should register your custom type registry bean whenever implementing federated GraphQL schema with
16+
extended types_.
17+
* **GraphQLSchema** - GraphQL schema generated based on the schema generator configuration and `Query`, `Mutation` and
18+
`Subscription` objects available in the application context
19+
* **DataFetcherExceptionHandler** - GraphQL exception handler used from the various execution strategies, defaults to
20+
[KotlinDataFetcherExceptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/exception/KotlinDataFetcherExceptionHandler.kt)
21+
* **GraphQL** - `graphql-java` GraphQL query execution engine generated using `GraphQLSchema` with default async
22+
execution strategies. GraphQL engine can be customized by optionally providing a list of
23+
[Instrumentation](https://www.graphql-java.com/documentation/v13/instrumentation/) beans (which can be ordered by implementing Spring
24+
Ordered interface), [ExecutionIdProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/ExecutionIdProvider.java)
25+
and
26+
[PreparsedDocumentProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/preparsed/PreparsedDocumentProvider.java)
27+
in the application context.
28+
* **DataLoaderRegistryFactory** - factory used to create DataLoaderRegistry instance per query execution. See [graphql-java documentation](https://www.graphql-java.com/documentation/v13/batching/)
29+
for more details
30+
* **QueryHandler** - handler invoked from GraphQL query route that executes the incoming request, defaults to
31+
[SimpleQueryHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/QueryHandler.kt)
32+
* **GraphQLContextFactory** - factory used by context WebFilter to generate GraphQL context based on the incoming
33+
request. GraphQL context can be any object. Defaults to empty
34+
[GraphQLContext](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/GraphQLContext.java)
35+
* **SubscriptionHandler** - Web socket handler for executing GraphQL subscriptions, defaults to
36+
[SimpleSubscriptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionHandler.kt#L49),
37+
created only if `Subscription` bean is available in the context
38+
* **WebSocketHandlerAdapter** - [see Spring
39+
documentation](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/socket/server/support/WebSocketHandlerAdapter.html),
40+
created only if `Subscription` bean is available in the context
41+
42+
The following beans are currently automatically created and cannot be disabled:
43+
44+
* Web filter for generating and populating GraphQL context
45+
* Default routes for GraphQL queries/mutations and SDL endpoint
46+
* Default route for Prisma Labs Playground, created only if playground is enabled
47+
* Default `ApolloSubscriptionProtocolHandler` for handling GraphQL subscriptions, created only if `Subscription` bean is available in the context
48+
* Default `SubscriptionWebSocketHandler` that utilizes above subscription protocol handler, created only if `Subscription` bean is available in the context
49+
* Default subscription handler mapping, created only if `Subscription` bean is available in the context

‎docs/server/spring-config.md

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎docs/server/spring-properties.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: spring-properties
3+
title: Configuration Properties
4+
---
5+
6+
`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)
7+
to provide various customizations of the auto-configuration library. All applicable configuration properties expose [configuration
8+
metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html) that provides
9+
details on the supported configuration properties.
10+
11+
| Property | Description | Default Value |
12+
|----------|-------------|---------------|
13+
| graphql.endpoint | GraphQL server endpoint | "graphql" |
14+
| graphql.packages | List of supported packages that can contain GraphQL schema type definitions | |
15+
| graphql.federation.enabled | Boolean flag indicating whether to generate federated GraphQL model | |
16+
| graphql.subscriptions.endpoint | GraphQL subscriptions endpoint | "subscriptions" |
17+
| graphql.subscriptions.keepAliveInterval | Keep the websocket alive and send a message to the client every interval in ms. Defaults to not sending messages | null |
18+
| graphql.playground.enabled | Boolean flag indicating whether to enabled Prisma Labs Playground GraphQL IDE | |
19+
| graphql.playground.endpoint | Prisma Labs Playground GraphQL IDE endpoint | "playground" |

‎website/sidebars.json

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,10 @@
3939
"federated/federated-directives",
4040
"federated/type-resolution"
4141
],
42-
"Spring Server": [
43-
"server/spring",
44-
"server/spring-config"
42+
"Server": [
43+
"server/spring-auto-config",
44+
"server/spring-beans",
45+
"server/spring-properties"
4546
],
4647
"Contributors": [
4748
"contributors/release-proc"

0 commit comments

Comments
 (0)