or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-properties.mdcore-infrastructure.mddata-integration.mdindex.mdobservability-integration.mdsecurity-integration.mdtesting-support.mdtransport-support.mdweb-integration.md
tile.json

tessl/maven-org-springframework-boot--spring-boot-starter-graphql

Starter for building GraphQL applications with Spring GraphQL

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springframework.boot/spring-boot-starter-graphql@3.5.x

To install, run

npx @tessl/cli install tessl/maven-org-springframework-boot--spring-boot-starter-graphql@3.5.0

index.mddocs/

Spring Boot GraphQL Starter

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.

Package Information

  • Package Name: spring-boot-starter-graphql
  • Package Type: Maven
  • Group ID: org.springframework.boot
  • Language: Java
  • Installation: Add dependency to Maven or Gradle

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-graphql</artifactId>
    <version>3.5.3</version>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-graphql:3.5.3'

Core Setup

The starter provides zero-configuration GraphQL setup through Spring Boot's auto-configuration mechanism. Simply add the dependency and place your GraphQL schema files:

// No explicit configuration needed - auto-configured
@SpringBootApplication
public class GraphQLApplication {
    public static void main(String[] args) {
        SpringApplication.run(GraphQLApplication.class, args);
    }
}

Schema files location (default):

src/main/resources/
└── graphql/
    ├── schema.graphqls
    └── additional-types.graphqls

Basic Usage

Simple GraphQL Controller

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.stereotype.Controller;

@Controller
public class BookController {
    
    @QueryMapping
    public List<Book> books() {
        return bookService.findAll();
    }
    
    @QueryMapping
    public Book bookById(@Argument String id) {
        return bookService.findById(id);
    }
    
    @MutationMapping
    public Book addBook(@Argument BookInput book) {
        return bookService.save(book);
    }
}

GraphQL Schema

type Query {
    books: [Book]
    bookById(id: ID!): Book
}

type Mutation {
    addBook(book: BookInput!): Book
}

type Book {
    id: ID!
    title: String!
    author: String!
    isbn: String
}

input BookInput {
    title: String!
    author: String!
    isbn: String
}

Architecture

The starter follows Spring Boot's auto-configuration pattern:

  • Auto-Configuration Classes: Automatically configure GraphQL infrastructure
  • Configuration Properties: Externalize GraphQL settings via application.properties
  • Web Integration: Seamless integration with Spring MVC and WebFlux
  • Extension Points: Customize behavior through Spring beans and interfaces

Capabilities

Core GraphQL Infrastructure

Provides the fundamental GraphQL execution engine and schema loading capabilities.

// Auto-configured beans available for injection
@Autowired
private GraphQlSource graphQlSource;

@Autowired 
private ExecutionGraphQlService executionGraphQlService;

@Autowired
private BatchLoaderRegistry batchLoaderRegistry;

Core Infrastructure

Configuration Properties

Comprehensive configuration options for all GraphQL features through Spring Boot properties.

// Configuration prefix: spring.graphql
@ConfigurationProperties("spring.graphql")
public class GraphQlProperties {
    private String path = "/graphql";
    private Http http = new Http();
    private Schema schema = new Schema();
    private Graphiql graphiql = new Graphiql();
    // Additional nested properties...
}

Configuration Properties

Web Integration

Auto-configuration for both Spring MVC (servlet) and Spring WebFlux (reactive) web stacks.

// MVC Integration - Auto-configured handlers
@Autowired
private GraphQlHttpHandler graphQlHttpHandler;

@Autowired
private WebGraphQlHandler webGraphQlHandler;

// WebFlux Integration - Auto-configured reactive handlers  
@Autowired
private org.springframework.graphql.server.webflux.GraphQlHttpHandler reactiveHandler;

Web Integration

Data Integration

Automatic integration with Spring Data repositories for seamless database access.

// Query by Example integration - automatically configured
public interface BookRepository extends JpaRepository<Book, String>, 
                                        QueryByExampleExecutor<Book> {
}

// Querydsl integration - automatically configured when available
public interface AuthorRepository extends JpaRepository<Author, String>,
                                          QuerydslPredicateExecutor<Author> {
}

Data Integration

Security Integration

Built-in integration with Spring Security for authentication and authorization.

// Security configuration for GraphQL endpoints
@Configuration
@EnableWebSecurity
public class GraphQlSecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/graphql").authenticated()
            )
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt)
            .build();
    }
}

Security Integration

Transport Support

Multiple transport protocols including HTTP, WebSocket, Server-Sent Events, and RSocket.

// WebSocket subscription support
@SubscriptionMapping
public Flux<BookEvent> bookUpdates() {
    return bookEventPublisher.getEvents();
}

// RSocket integration
@MessageMapping("books.request-response")
public Mono<Book> getBook(String id) {
    return bookService.findByIdAsync(id);
}

Transport Support

Testing Support

Comprehensive testing infrastructure for GraphQL applications.

@GraphQlTest
class BookControllerTest {
    
    @Autowired
    private GraphQlTester graphQlTester;
    
    @Test
    void shouldGetBooks() {
        graphQlTester
            .documentName("books")
            .execute()
            .path("books")
            .entityList(Book.class)
            .hasSize(2);
    }
}

Testing Support

Observability Integration

Built-in metrics, tracing, and monitoring capabilities through Spring Boot Actuator.

// Observability configuration
@Configuration
public class GraphQlObservabilityConfig {
    
    @Bean
    public ObservationRegistryCustomizer<ObservationRegistry> customizer() {
        return registry -> registry.observationConfig()
            .observationHandler(new GraphQlObservationHandler());
    }
}

Observability Integration

Common Types

Core Configuration Types

// Main configuration properties
public class GraphQlProperties {
    public static class Http {
        private String path = "/graphql";
        private Sse sse = new Sse();
    }
    
    public static class Schema {
        private String[] locations = {"classpath:graphql/**/"};
        private String[] fileExtensions = {".graphqls", ".gqls"};
        private Resource[] additionalFiles = {};
        private Inspection inspection = new Inspection();
        private Introspection introspection = new Introspection();
    }
    
    public static class Graphiql {
        private String path = "/graphiql"; 
        private boolean enabled = false;
    }
    
    public static class Websocket {
        private String path;
        private Duration connectionInitTimeout = Duration.ofSeconds(60);
        private Duration keepAlive;
    }
}

Extension Point Interfaces

// Customization interfaces - implement and register as Spring beans
public interface RuntimeWiringConfigurer {
    void configure(RuntimeWiring.Builder builder);
}

public interface GraphQlSourceBuilderCustomizer {
    void customize(GraphQlSource.SchemaResourceBuilder builder);
}

public interface WebGraphQlInterceptor {
    Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, WebGraphQlInterceptorChain chain);
}

public interface DataFetcherExceptionResolver {
    Mono<List<GraphQLError>> resolveException(DataFetcherExceptionResolverEnvironment environment);
}

GraphQL Annotations

// Controller annotations for GraphQL endpoints
@QueryMapping // Maps to GraphQL Query fields
@MutationMapping // Maps to GraphQL Mutation fields  
@SubscriptionMapping // Maps to GraphQL Subscription fields
@SchemaMapping // Maps to specific GraphQL types
@BatchMapping // Batch loading for N+1 problem prevention
@Argument // Method parameter mapping
@ContextValue // Access to GraphQL context