0
# Spring Boot GraphQL Starter
1
2
Spring Boot GraphQL Starter provides comprehensive auto-configuration for building GraphQL applications using Spring GraphQL. It automatically configures GraphQL schema loading, execution engines, and web integration for both servlet-based (Spring MVC) and reactive (Spring WebFlux) applications, with built-in support for GraphQL security, data integration, RSocket transport, and observability features.
3
4
## Package Information
5
6
- **Package Name**: spring-boot-starter-graphql
7
- **Package Type**: Maven
8
- **Group ID**: org.springframework.boot
9
- **Language**: Java
10
- **Installation**: Add dependency to Maven or Gradle
11
12
Maven:
13
```xml
14
<dependency>
15
<groupId>org.springframework.boot</groupId>
16
<artifactId>spring-boot-starter-graphql</artifactId>
17
<version>3.5.3</version>
18
</dependency>
19
```
20
21
Gradle:
22
```gradle
23
implementation 'org.springframework.boot:spring-boot-starter-graphql:3.5.3'
24
```
25
26
## Core Setup
27
28
The starter provides zero-configuration GraphQL setup through Spring Boot's auto-configuration mechanism. Simply add the dependency and place your GraphQL schema files:
29
30
```java
31
// No explicit configuration needed - auto-configured
32
@SpringBootApplication
33
public class GraphQLApplication {
34
public static void main(String[] args) {
35
SpringApplication.run(GraphQLApplication.class, args);
36
}
37
}
38
```
39
40
Schema files location (default):
41
```
42
src/main/resources/
43
└── graphql/
44
├── schema.graphqls
45
└── additional-types.graphqls
46
```
47
48
## Basic Usage
49
50
### Simple GraphQL Controller
51
```java
52
import org.springframework.graphql.data.method.annotation.QueryMapping;
53
import org.springframework.graphql.data.method.annotation.MutationMapping;
54
import org.springframework.stereotype.Controller;
55
56
@Controller
57
public class BookController {
58
59
@QueryMapping
60
public List<Book> books() {
61
return bookService.findAll();
62
}
63
64
@QueryMapping
65
public Book bookById(@Argument String id) {
66
return bookService.findById(id);
67
}
68
69
@MutationMapping
70
public Book addBook(@Argument BookInput book) {
71
return bookService.save(book);
72
}
73
}
74
```
75
76
### GraphQL Schema
77
```graphql
78
type Query {
79
books: [Book]
80
bookById(id: ID!): Book
81
}
82
83
type Mutation {
84
addBook(book: BookInput!): Book
85
}
86
87
type Book {
88
id: ID!
89
title: String!
90
author: String!
91
isbn: String
92
}
93
94
input BookInput {
95
title: String!
96
author: String!
97
isbn: String
98
}
99
```
100
101
## Architecture
102
103
The starter follows Spring Boot's auto-configuration pattern:
104
105
- **Auto-Configuration Classes**: Automatically configure GraphQL infrastructure
106
- **Configuration Properties**: Externalize GraphQL settings via `application.properties`
107
- **Web Integration**: Seamless integration with Spring MVC and WebFlux
108
- **Extension Points**: Customize behavior through Spring beans and interfaces
109
110
## Capabilities
111
112
### Core GraphQL Infrastructure
113
114
Provides the fundamental GraphQL execution engine and schema loading capabilities.
115
116
```java { .api }
117
// Auto-configured beans available for injection
118
@Autowired
119
private GraphQlSource graphQlSource;
120
121
@Autowired
122
private ExecutionGraphQlService executionGraphQlService;
123
124
@Autowired
125
private BatchLoaderRegistry batchLoaderRegistry;
126
```
127
128
[Core Infrastructure](./core-infrastructure.md)
129
130
### Configuration Properties
131
132
Comprehensive configuration options for all GraphQL features through Spring Boot properties.
133
134
```java { .api }
135
// Configuration prefix: spring.graphql
136
@ConfigurationProperties("spring.graphql")
137
public class GraphQlProperties {
138
private String path = "/graphql";
139
private Http http = new Http();
140
private Schema schema = new Schema();
141
private Graphiql graphiql = new Graphiql();
142
// Additional nested properties...
143
}
144
```
145
146
[Configuration Properties](./configuration-properties.md)
147
148
### Web Integration
149
150
Auto-configuration for both Spring MVC (servlet) and Spring WebFlux (reactive) web stacks.
151
152
```java { .api }
153
// MVC Integration - Auto-configured handlers
154
@Autowired
155
private GraphQlHttpHandler graphQlHttpHandler;
156
157
@Autowired
158
private WebGraphQlHandler webGraphQlHandler;
159
160
// WebFlux Integration - Auto-configured reactive handlers
161
@Autowired
162
private org.springframework.graphql.server.webflux.GraphQlHttpHandler reactiveHandler;
163
```
164
165
[Web Integration](./web-integration.md)
166
167
### Data Integration
168
169
Automatic integration with Spring Data repositories for seamless database access.
170
171
```java { .api }
172
// Query by Example integration - automatically configured
173
public interface BookRepository extends JpaRepository<Book, String>,
174
QueryByExampleExecutor<Book> {
175
}
176
177
// Querydsl integration - automatically configured when available
178
public interface AuthorRepository extends JpaRepository<Author, String>,
179
QuerydslPredicateExecutor<Author> {
180
}
181
```
182
183
[Data Integration](./data-integration.md)
184
185
### Security Integration
186
187
Built-in integration with Spring Security for authentication and authorization.
188
189
```java { .api }
190
// Security configuration for GraphQL endpoints
191
@Configuration
192
@EnableWebSecurity
193
public class GraphQlSecurityConfig {
194
195
@Bean
196
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
197
return http
198
.authorizeHttpRequests(auth -> auth
199
.requestMatchers("/graphql").authenticated()
200
)
201
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt)
202
.build();
203
}
204
}
205
```
206
207
[Security Integration](./security-integration.md)
208
209
### Transport Support
210
211
Multiple transport protocols including HTTP, WebSocket, Server-Sent Events, and RSocket.
212
213
```java { .api }
214
// WebSocket subscription support
215
@SubscriptionMapping
216
public Flux<BookEvent> bookUpdates() {
217
return bookEventPublisher.getEvents();
218
}
219
220
// RSocket integration
221
@MessageMapping("books.request-response")
222
public Mono<Book> getBook(String id) {
223
return bookService.findByIdAsync(id);
224
}
225
```
226
227
[Transport Support](./transport-support.md)
228
229
### Testing Support
230
231
Comprehensive testing infrastructure for GraphQL applications.
232
233
```java { .api }
234
@GraphQlTest
235
class BookControllerTest {
236
237
@Autowired
238
private GraphQlTester graphQlTester;
239
240
@Test
241
void shouldGetBooks() {
242
graphQlTester
243
.documentName("books")
244
.execute()
245
.path("books")
246
.entityList(Book.class)
247
.hasSize(2);
248
}
249
}
250
```
251
252
[Testing Support](./testing-support.md)
253
254
### Observability Integration
255
256
Built-in metrics, tracing, and monitoring capabilities through Spring Boot Actuator.
257
258
```java { .api }
259
// Observability configuration
260
@Configuration
261
public class GraphQlObservabilityConfig {
262
263
@Bean
264
public ObservationRegistryCustomizer<ObservationRegistry> customizer() {
265
return registry -> registry.observationConfig()
266
.observationHandler(new GraphQlObservationHandler());
267
}
268
}
269
```
270
271
[Observability Integration](./observability-integration.md)
272
273
## Common Types
274
275
### Core Configuration Types
276
277
```java { .api }
278
// Main configuration properties
279
public class GraphQlProperties {
280
public static class Http {
281
private String path = "/graphql";
282
private Sse sse = new Sse();
283
}
284
285
public static class Schema {
286
private String[] locations = {"classpath:graphql/**/"};
287
private String[] fileExtensions = {".graphqls", ".gqls"};
288
private Resource[] additionalFiles = {};
289
private Inspection inspection = new Inspection();
290
private Introspection introspection = new Introspection();
291
}
292
293
public static class Graphiql {
294
private String path = "/graphiql";
295
private boolean enabled = false;
296
}
297
298
public static class Websocket {
299
private String path;
300
private Duration connectionInitTimeout = Duration.ofSeconds(60);
301
private Duration keepAlive;
302
}
303
}
304
```
305
306
### Extension Point Interfaces
307
308
```java { .api }
309
// Customization interfaces - implement and register as Spring beans
310
public interface RuntimeWiringConfigurer {
311
void configure(RuntimeWiring.Builder builder);
312
}
313
314
public interface GraphQlSourceBuilderCustomizer {
315
void customize(GraphQlSource.SchemaResourceBuilder builder);
316
}
317
318
public interface WebGraphQlInterceptor {
319
Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, WebGraphQlInterceptorChain chain);
320
}
321
322
public interface DataFetcherExceptionResolver {
323
Mono<List<GraphQLError>> resolveException(DataFetcherExceptionResolverEnvironment environment);
324
}
325
```
326
327
### GraphQL Annotations
328
329
```java { .api }
330
// Controller annotations for GraphQL endpoints
331
@QueryMapping // Maps to GraphQL Query fields
332
@MutationMapping // Maps to GraphQL Mutation fields
333
@SubscriptionMapping // Maps to GraphQL Subscription fields
334
@SchemaMapping // Maps to specific GraphQL types
335
@BatchMapping // Batch loading for N+1 problem prevention
336
@Argument // Method parameter mapping
337
@ContextValue // Access to GraphQL context
338
```