Create a project using Spring Initializr and add Spring for GraphQL dependencies; 2. Define GraphQL schema in the schema.graphqls file; 3. Create Book record class as data model; 4. Implement query parser with @Controller and @QueryMapping; 5. Start the application and test queries through http://localhost:8080/graphql; 6. Enable GraphiQL in the configuration file to use an interactive UI; 7. Optionally add Mutation in the schema and implement the change method with @MutationMapping; finally build a type-safe, production-ready GraphQL API through schema-first. The whole process integrates naturally and smoothly with Spring Boot, and runs without additional configuration.

Building a GraphQL API with Java and Spring is straightforward thanks to Spring for GraphQL , a module introduced by the Spring team to simplify integrating GraphQL into Spring Boot applications. It provides first-class support for building GraphQL servers using familiar Spring patterns—like annotations, dependency injection, and testing utilities.

Here's how to set up a working GraphQL API in Java with Spring Boot.

? 1. Set Up the Project with Required Dependencies

Start by creating a Spring Boot project using Spring Initializr and include:

• Spring Web (for embedded server)
• Spring for GraphQL (the core module)
• Spring Boot DevTools (optional, for hot reload)
• Lombok (optional, reduces boilerplate)

Or manually add the dependency in pom.xml (for Maven):

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

For Gradle:

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

Spring Boot 3 includes automatic configuration for GraphQL, so no extra setup is needed to get started.

? 2. Define Your Schema ( .graphqls file)

Create a file named schema.graphqls under src/main/resources/graphql :

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

type Book {
    id: ID!
    title: String!
    author: String!
    pages: Int
    chapterCount: Int
}

This defines:

• Two queries: bookById and allBooks
• A Book type with several fields

? Note: Spring for GraphQL automatically detects .graphqls files on the classpath.

? 3. Create Data Models

Map the GraphQL types to Java classes:

 // Book.java
public record Book(String id, String title, String author, Integer pages, Integer chapterCount) {}

Using record (Java 16 ) keeps it clean. Otherwise, use a standard class with getters.

? 4. Implement a Data Fetcher with @Controller

Use a Spring @Controller to implement resolvers:

 import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;

@Controller
public class BookController {

    private static final List<Book> BOOKS = List.of(
        new Book("1", "The Great Gatsby", "F. Scott Fitzgerald", 180, 9),
        new Book("2", "1984", "George Orwell", 328, 25),
        new Book("3", "Dune", "Frank Herbert", 688, 75)
    );

    private final AtomicInteger counter = new AtomicInteger(100);

    @QueryMapping
    public Book bookById(String id) {
        return BOOKS.stream()
            .filter(book -> book.id().equals(id))
            .findFirst()
            .orElse(null);
    }

    @QueryMapping
    public List<Book> allBooks() {
        return BOOKS;
    }
}

? @QueryMapping maps methods to GraphQL query fields. Parameter names must match schema input fields.

? 5. Test the API

Start the app with mvn spring-boot:run or via your IDE.

Go to: http://ipnx.cn/link/1d22a89ef605339c5e6580b577a57ad5 (if using GraphiQL)

Or send a POST request to http://localhost:8080/graphql :

 {
  "query": "{ allBooks { id title author pages } }"
}

Sample response:

 {
  "data": {
    "allBooks": [
      {
        "id": "1",
        "title": "The Great Gatsby",
        "author": "F. Scott Fitzgerald",
        "pages": 180
      },
      ...
    ]
  }
}

You can also query a single book:

 {
  bookById(id: "2") {
    title
    author
  }
}

? 6. Enable GraphiQL (Interactive UI)

Add this to application.properties :

 spring.graphql.graphhiql.enabled=true

Or in application.yml :

 spring:
  graphql:
    graphiql:
      enabled: true

Now you can explore and test your schema interactively.

? 7. Add Mutations (Optional)

Extend schema in schema.graphqls :

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

extend type Query {
    bookById(id: ID!): Book
}

Add a mutation method:

 @MutationMapping
public Book createBook(String title, String author, Integer pages) {
    String id = String.valueOf(counter.incrementAndGet());
    Book newBook = new Book(id, title, author, pages, null);
    // In real apps: save to DB
    return newBook;
}

Now you can run:

 mutation {
  createBook(title: "New Book", author: "Me") {
    id
    title
  }
}

Final Notes

• No need for controllers with @RequestMapping – Spring for GraphQL uses annotated methods directly.
• Supports annotations like @SchemaMapping for more complex nested resolvers.
• Integrates with Spring Security , Data Fetching (DataLoader) , and Reactive Streams .
• Schema-first approach encourages clear contract design.

Building a GraphQL API with Java and Spring is now as natural as REST—just define your schema, write annotated methods, and let Spring handle the wiring. It's clean, type-safe, and production-ready.

Basically, if you know Spring and a bit of GraphQL, you're already halfway there.

The above is the detailed content of Building a GraphQL API with Java and Spring for GraphQL. For more information, please follow other related articles on the PHP Chinese website!