GraphQL provides a flexilbe approach to API design, allowing clients to request exactly the data they need. This guide walks through setting up GraphQL in a Spring Boot environment with practical examples.

Project Configuration

Create a new Spring Boot project and include the following dependencies in your pom.xml:

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>11.1.0</version>
</dependency>
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphiql-spring-boot-starter</artifactId>
    <version>11.1.0</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>altair-spring-boot-starter</artifactId>
    <version>11.1.0</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-java-tools</artifactId>
    <version>11.1.0</version>
</dependency>

Schema Definition

Define the GraphQL schema in src/main/resources/schema.graphqls:

type Query {
    findBookById(id: ID!): Book
    listBooks: [Book]
}

type Mutation {
    createBook(title: String!, author: String!): Book
}

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

Domain Model

Create the corresponding Java entity:

package com.example.graphql.model;

public class Book {
    private String id;
    private String title;
    private String author;

    public Book() {}

    public Book(String id, String title, String author) {
        this.id = id;
        this.title = title;
        this.author = author;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getAuthor() {
        return author;
    }

    public void setAuthor(String author) {
        this.author = author;
    }
}

Service Layer

Implement the business logic in a service class:

package com.example.graphql.service;

import com.example.graphql.model.Book;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

@Service
public class BookService {
    
    private final List<Book> repository = new ArrayList<>();

    public Optional<Book> findById(String id) {
        return repository.stream()
                .filter(book -> book.getId().equals(id))
                .findFirst();
    }

    public List<Book> findAll() {
        return new ArrayList<>(repository);
    }

    public Book save(String title, String author) {
        Book newBook = new Book();
        newBook.setId(java.util.UUID.randomUUID().toString());
        newBook.setTitle(title);
        newBook.setAuthor(author);
        repository.add(newBook);
        return newBook;
    }
}

Resolver Implementation

Create query and mutation resolvers that hendle GraphQL operations:

package com.example.graphql.resolver;

import com.example.graphql.model.Book;
import com.example.graphql.service.BookService;
import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class BookQueryResolver implements GraphQLQueryResolver {
    
    private final BookService bookService;

    public BookQueryResolver(BookService bookService) {
        this.bookService = bookService;
    }

    public Book findBookById(String id) {
        return bookService.findById(id).orElse(null);
    }

    public List<Book> listBooks() {
        return bookService.findAll();
    }
}

package com.example.graphql.resolver;

import com.example.graphql.model.Book;
import com.example.graphql.service.BookService;
import com.coxautodev.graphql.tools.GraphQLMutationResolver;
import org.springframework.stereotype.Component;

@Component
public class BookMutationResolver implements GraphQLMutationResolver {
    
    private final BookService bookService;

    public BookMutationResolver(BookService bookService) {
        this.bookService = bookService;
    }

    public Book createBook(String title, String author) {
        return bookService.save(title, author);
    }
}

Application Configuration

Add GraphQL settings to application.yml:

graphql:
  servlet:
    mapping: /graphql
    enabled: true
  tools:
    schema-location-pattern: "**/*.graphqls"
  graphiql:
    enabled: true
    endpoint: /graphql
  altair:
    enabled: true
    endpoint: /graphql

Testing the API

Run the application and access the GraphQL playground at http://localhost:8080/graphiql or http://localhost:8080/altair.

Retrieve all books:

query {
  listBooks {
    id
    title
    author
  }
}

Create a new book:

mutation {
  createBook(title: "Clean Code", author: "Robert C. Martin") {
    id
    title
    author
  }
}