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
```