Lecture 283: Installing and Setting Up Spring GraphQL

Spring and its ecosystem make app development efficient, and integrating with GraphQL lets you use a modern, flexible, and powerful way to work with data. GraphQL exposes a single endpoint for all operations (queries and mutations), simplifying client-server interactions. Combined with Spring, you get a powerful tool for building APIs that can easily replace or complement REST.

1. Installing Spring GraphQL: creating the project

Let's start by setting up a new Spring Boot project that supports GraphQL. We'll use Spring Initializr to quickly scaffold a project template.

Using Spring Initializr

1. Open Spring Initializr.
2. Choose:
   • Project: Maven (you can also use Gradle if you prefer).
   • Language: Java.
   • Spring Boot: version 2.7.0 or newer (GraphQL support starts from 2.7.0).
3. Add the required dependencies:
   • Spring Web
   • Spring Boot Starter GraphQL
   • Spring Boot DevTools (for fast app reloads — super handy during development).
4. Download the project template and import it into your favorite IDE (IntelliJ IDEA, Eclipse, etc.).

Example pom.xml

Your pom.xml should look roughly like this:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.graphql-java-kickstart</groupId>
        <artifactId>graphql-spring-boot-starter</artifactId>
        <version>12.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-graphql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
</dependencies>

Everything's ready to get started! Let's move on to configuring the GraphQL server.

2. Configuring the GraphQL server

GraphQL needs a schema and routing. Spring Boot makes this easy by automatically wiring up the schema and the entry point for GraphQL.

Folder for the schema

Create a folder named graphql inside src/main/resources. We'll keep our GraphQL schemas in that directory.

Defining the first schema

Create a file named schema.graphqls in the graphql folder. This is where you'll describe types and available operations. Here's a simple starter:

type Query {
    hello: String
}

This defines a simple hello operation that returns a string. Once the schema is ready, we'll wire up a handler for the query.

Endpoint setup

By default Spring Boot GraphQL configures the /graphql endpoint to handle all GraphQL requests. To check it, run your app and open http://localhost:8080/graphql in your browser.

At this point you'll see that the server is ready to interact. Now let's implement our first query handler.

3. Creating resolvers for Query

GraphQL uses "resolvers" to map operations (queries, mutations) to Java logic. For our first hello query, we'll create a resolver.

Creating the resolver

Add a new class to your project:

package com.example.graphql;

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

@Controller
public class GreetingController {

    @QueryMapping
    public String hello() {
        return "Hello from GraphQL!";
    }
}

Notes:

1. @Controller — tells Spring this class will handle requests.
2. @QueryMapping — binds the method to our hello query in the schema.

4. Testing GraphQL queries

You can test queries using the built-in GraphQL tool — GraphiQL, which is already integrated in Spring Boot.

1. Run the application.
2. Open in your browser: http://localhost:8080/graphiql.
3. Paste the following query:

   query {
       hello
   }
   

If everything's set up right, you'll see:

{
  "data": {
    "hello": "Hello from GraphQL!"
  }
}

Congrats! You've just created your first GraphQL application!

5. IDE setup for working with GraphQL

Plugin for IntelliJ IDEA

If you're using IntelliJ IDEA, a great tool for GraphQL is the GraphQL plugin from the JetBrains Marketplace. It helps you:

• Automatically validate your GraphQL schema.
• Highlight errors and autocomplete queries.
• Test queries right from the IDE.

Installation:

1. Open IntelliJ IDEA settings: File > Settings > Plugins.
2. Search for the GraphQL plugin and install it.
3. Restart the IDE.

Now you can easily edit and test your schemas and queries.

6. Advanced GraphQL server configuration

The Spring Boot GraphQL server supports configuration via application.properties or application.yml. For example:

spring.graphql.graphiql.enabled=true
spring.graphql.schema.printer.enabled=true

Here:

• spring.graphql.graphiql.enabled=true enables the built-in GraphiQL interface (enabled by default).
• spring.graphql.schema.printer.enabled=true prints your schema to the logs on startup (handy for verification).

7. Common errors and how to fix them

• Error: "No schema found". Make sure your schema file schema.graphqls is located in src/main/resources/graphql — that's the default path for GraphQL schemas in Spring Boot.
• Error: "Query [name] not found". If a query from the schema can't find a resolver, ensure the names match and the method is annotated with @QueryMapping.
• Error: "Circular dependency". This can happen when you have multiple beans with complex dependencies. Try using @Lazy or rethinking the architecture to resolve it.

You're now ready to tackle more complex schemas, queries, and mutations! We've taken the first step integrating GraphQL with Spring Boot. In the next lectures we'll dive deeper into building more advanced queries, mutations, and subscriptions.