0
# Configuration Properties
1

2
Spring Boot GraphQL Starter provides extensive configuration options through Spring Boot's configuration properties mechanism. All properties use the `spring.graphql` prefix and support environment-specific overrides.
3

4
## Main Configuration Class
5

6
```java { .api }
7
@ConfigurationProperties("spring.graphql")
8
public class GraphQlProperties {
9
    private final Http http = new Http();
10
    private final Graphiql graphiql = new Graphiql();
11
    private final Rsocket rsocket = new Rsocket();
12
    private final Schema schema = new Schema();
13
    private final Websocket websocket = new Websocket();
14
    
15
    // Getters for all nested properties
16
    public Http getHttp() { return this.http; }
17
    public Graphiql getGraphiql() { return this.graphiql; }
18
    public Schema getSchema() { return this.schema; }
19
    public Websocket getWebsocket() { return this.websocket; }
20
    public Rsocket getRsocket() { return this.rsocket; }
21
}
22
```
23

24
## HTTP Configuration
25

26
Configure HTTP endpoint settings and transport-specific options.
27

28
```java { .api }
29
public static class Http {
30
    private String path = "/graphql";
31
    private final Sse sse = new Sse();
32
    
33
    public String getPath() { return this.path; }
34
    public void setPath(String path) { this.path = path; }
35
    public Sse getSse() { return this.sse; }
36
}
37
```
38

39
### Configuration Examples
40

41
```properties
42
# HTTP endpoint path (default: /graphql)
43
spring.graphql.http.path=/api/graphql
44

45
# Server-Sent Events configuration
46
spring.graphql.http.sse.keep-alive=30s
47
spring.graphql.http.sse.timeout=60s
48
```
49

50
### Server-Sent Events (SSE)
51

52
```java { .api }
53
public static class Sse {
54
    private Duration keepAlive;
55
    private Duration timeout;
56
    
57
    public Duration getKeepAlive() { return this.keepAlive; }
58
    public void setKeepAlive(Duration keepAlive) { this.keepAlive = keepAlive; }
59
    public Duration getTimeout() { return this.timeout; }
60
    public void setTimeout(Duration timeout) { this.timeout = timeout; }
61
}
62
```
63

64
## Schema Configuration
65

66
Control GraphQL schema loading, validation, and development features.
67

68
```java { .api }
69
public static class Schema {
70
    private String[] locations = {"classpath:graphql/**/"};
71
    private String[] fileExtensions = {".graphqls", ".gqls"};
72
    private Resource[] additionalFiles = {};
73
    private final Inspection inspection = new Inspection();
74
    private final Introspection introspection = new Introspection();
75
    private final Printer printer = new Printer();
76
    
77
    // Getters and setters
78
    public String[] getLocations() { return this.locations; }
79
    public void setLocations(String[] locations) { this.locations = appendSlashIfNecessary(locations); }
80
    public String[] getFileExtensions() { return this.fileExtensions; }
81
    public void setFileExtensions(String[] fileExtensions) { this.fileExtensions = fileExtensions; }
82
    public Resource[] getAdditionalFiles() { return this.additionalFiles; }
83
    public void setAdditionalFiles(Resource[] additionalFiles) { this.additionalFiles = additionalFiles; }
84
}
85
```
86

87
### Schema Loading Configuration
88

89
```properties
90
# Schema file locations (default: classpath:graphql/**/)
91
spring.graphql.schema.locations=classpath:schemas/,classpath:types/
92

93
# Supported file extensions (default: .graphqls, .gqls)
94
spring.graphql.schema.file-extensions=.graphqls,.gqls,.graphql
95

96
# Additional schema files
97
spring.graphql.schema.additional-files=classpath:extra-schema.graphqls
98
```
99

100
### Schema Inspection
101

102
```java { .api }
103
public static class Inspection {
104
    private boolean enabled = true;
105
    
106
    public boolean isEnabled() { return this.enabled; }
107
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
108
}
109
```
110

111
```properties
112
# Enable schema-to-application mapping validation (default: true)
113
spring.graphql.schema.inspection.enabled=true
114
```
115

116
### Schema Introspection
117

118
```java { .api }
119
public static class Introspection {
120
    private boolean enabled = true;
121
    
122
    public boolean isEnabled() { return this.enabled; }
123
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
124
}
125
```
126

127
```properties
128
# Enable field introspection at schema level (default: true)
129
# Disable in production for security
130
spring.graphql.schema.introspection.enabled=false
131
```
132

133
### Schema Printer
134

135
```java { .api }
136
public static class Printer {
137
    private boolean enabled = false;
138
    
139
    public boolean isEnabled() { return this.enabled; }
140
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
141
}
142
```
143

144
```properties
145
# Enable schema printer endpoint at /graphql/schema (default: false)
146
spring.graphql.schema.printer.enabled=true
147
```
148

149
## GraphiQL Configuration
150

151
Configure the built-in GraphiQL development interface.
152

153
```java { .api }
154
public static class Graphiql {
155
    private String path = "/graphiql";
156
    private boolean enabled = false;
157
    
158
    public String getPath() { return this.path; }
159
    public void setPath(String path) { this.path = path; }
160
    public boolean isEnabled() { return this.enabled; }
161
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
162
}
163
```
164

165
### Configuration Examples
166

167
```properties
168
# Enable GraphiQL UI (default: false)
169
spring.graphql.graphiql.enabled=true
170

171
# GraphiQL endpoint path (default: /graphiql)
172
spring.graphql.graphiql.path=/graphql-ui
173
```
174

175
## WebSocket Configuration
176

177
Configure WebSocket transport for GraphQL subscriptions.
178

179
```java { .api }
180
public static class Websocket {
181
    private String path;
182
    private Duration connectionInitTimeout = Duration.ofSeconds(60);
183
    private Duration keepAlive;
184
    
185
    public String getPath() { return this.path; }
186
    public void setPath(String path) { this.path = path; }
187
    public Duration getConnectionInitTimeout() { return this.connectionInitTimeout; }
188
    public void setConnectionInitTimeout(Duration timeout) { this.connectionInitTimeout = timeout; }
189
    public Duration getKeepAlive() { return this.keepAlive; }
190
    public void setKeepAlive(Duration keepAlive) { this.keepAlive = keepAlive; }
191
}
192
```
193

194
### Configuration Examples
195

196
```properties
197
# Enable WebSocket support by setting path
198
spring.graphql.websocket.path=/graphql-ws
199

200
# Connection initialization timeout (default: 60s)
201
spring.graphql.websocket.connection-init-timeout=30s
202

203
# Keep-alive interval for WebSocket connections
204
spring.graphql.websocket.keep-alive=10s
205
```
206

207
## RSocket Configuration
208

209
Configure RSocket transport for GraphQL over RSocket.
210

211
```java { .api }
212
public static class Rsocket {
213
    private String mapping;
214
    
215
    public String getMapping() { return this.mapping; }
216
    public void setMapping(String mapping) { this.mapping = mapping; }
217
}
218
```
219

220
### Configuration Examples
221

222
```properties
223
# RSocket message handler mapping
224
spring.graphql.rsocket.mapping=graphql
225
```
226

227
## CORS Configuration
228

229
Configure Cross-Origin Resource Sharing for GraphQL endpoints.
230

231
```java { .api }
232
@ConfigurationProperties("spring.graphql.cors")
233
public class GraphQlCorsProperties {
234
    private List<String> allowedOrigins;
235
    private List<String> allowedOriginPatterns;
236
    private List<String> allowedHeaders;
237
    private List<String> allowedMethods;
238
    private List<String> exposedHeaders;
239
    private Boolean allowCredentials;
240
    private Duration maxAge;
241
    
242
    // Standard CORS configuration methods
243
    public CorsConfiguration toCorsConfiguration() {
244
        // Converts properties to Spring's CorsConfiguration
245
    }
246
}
247
```
248

249
### CORS Configuration Examples
250

251
```properties
252
# CORS configuration for GraphQL endpoints
253
spring.graphql.cors.allowed-origins=http://localhost:3000,https://example.com
254
spring.graphql.cors.allowed-methods=GET,POST
255
spring.graphql.cors.allowed-headers=*
256
spring.graphql.cors.allow-credentials=true
257
spring.graphql.cors.max-age=3600
258
```
259

260
## Deprecated Properties
261

262
### Legacy Path Configuration
263

264
```java { .api }
265
// Deprecated in Spring Boot 3.5.0
266
@DeprecatedConfigurationProperty(replacement = "spring.graphql.http.path", since = "3.5.0")
267
@Deprecated(since = "3.5.0", forRemoval = true)
268
public String getPath() {
269
    return getHttp().getPath();
270
}
271
```
272

273
### Legacy SSE Configuration
274

275
```java { .api }
276
@Deprecated(since = "3.5.1", forRemoval = true)
277
public static final class DeprecatedSse {
278
    @DeprecatedConfigurationProperty(replacement = "spring.graphql.http.sse.timeout", since = "3.5.0")
279
    @Deprecated(since = "3.5.0", forRemoval = true)
280
    public Duration getTimeout() {
281
        return this.sse.getTimeout();
282
    }
283
}
284
```
285

286
## Environment-Specific Configuration
287

288
### Development Configuration
289

290
```yaml
291
# application-dev.yml
292
spring:
293
  graphql:
294
    http:
295
      path: /graphql
296
    graphiql:
297
      enabled: true
298
      path: /graphiql
299
    schema:
300
      inspection:
301
        enabled: true
302
      introspection:
303
        enabled: true
304
      printer:
305
        enabled: true
306
    websocket:
307
      path: /graphql-ws
308
      keep-alive: 30s
309
```
310

311
### Production Configuration
312

313
```yaml
314
# application-prod.yml
315
spring:
316
  graphql:
317
    http:
318
      path: /api/graphql
319
      sse:
320
        timeout: 30s
321
        keep-alive: 15s
322
    graphiql:
323
      enabled: false
324
    schema:
325
      inspection:
326
        enabled: false
327
      introspection:
328
        enabled: false
329
      printer:
330
        enabled: false
331
    cors:
332
      allowed-origins: 
333
        - https://app.example.com
334
        - https://admin.example.com
335
      allowed-methods: POST
336
      allow-credentials: true
337
      max-age: 3600
338
```
339

340
## Configuration Validation
341

342
The starter validates configuration properties at startup:
343

344
- Schema locations must be valid resource patterns
345
- File extensions must start with a dot
346
- Timeout and duration values must be positive
347
- CORS configuration must be complete if specified
348

349
Invalid configurations result in clear error messages during application startup.
350

351
## Integration with Spring Boot Features
352

353
### Actuator Integration
354

355
```properties
356
# Expose GraphQL endpoint info via actuator
357
management.endpoints.web.exposure.include=health,info,graphql
358
management.endpoint.graphql.enabled=true
359
```
360

361
### Configuration Metadata
362

363
The starter provides configuration metadata for IDE autocompletion and validation:
364

365
```json
366
{
367
  "properties": [
368
    {
369
      "name": "spring.graphql.http.path",
370
      "type": "java.lang.String",
371
      "description": "Path at which to expose a GraphQL request HTTP endpoint.",
372
      "defaultValue": "/graphql"
373
    }
374
  ]
375
}
376
```
377

378
This enables rich IDE support with autocompletion, validation, and documentation tooltips.