Long story short, we will see:

• how to prepare a GraphQL schema,
• what imports are necessary to utilize suspended functions,
• how to expose queries, mutations, and map schema with annotated controllers,
• exception handling with GraphQlExceptionHandler

Create Project

As the first step, let’s prepare a brand new project.

To do so, let’s navigate to the Spring Initializr page and select the following imports:

The project metadata are totally up to you, but when it comes to the dependencies, we must select the Spring Reactive Web and Spring for GraphQL.

Thanks to the first one, Spring Boot configures a reactive web stack based on Project Reactor and Netty instead of Tomcat. And given we want to work with GraphQL and Kotlin coroutines, then this is a must-have for us.

The second provides support for Spring applications built on GraphQL Java. Moreover, it is the successor of the GraphQL Java Spring project from the GraphQL Java team.

Lastly, let’s download the zip package, extract and import it to our IDE.

Define GraphQL Schema

What is GraphQL Schema?

If you have ever worked with GraphQL before, then you know that compared to the REST, everything starts with schema definition.

If you haven’t, then GraphQL schema is a file typically written with Schema Definition Language (SDL) that describes how our API clients can interact with our server. To be more specific, inside it, we define the structure of returned data, as well as how consumers can fetch or send us the payloads.

And even though it may sound like a GraphQL substitute for OpenAPI specs, it is something more. In REST, OpenAPI docs are a nice addition to our project. In GraphQL, our services continuously utilize the schema definition to validate and execute requests against it.

And if you would like to learn more about GraphQL schema, then check out the official documentation later. But for now, let’s focus on the Spring / GraphQL / Kotlin combination 😉

schema.graphql in Spring

As the first step, let’s head to the resources > graphql directory in our project, and let’s insert the schema.graphql file:

type Query {
  article(id: ID!): Article
  articles: [Article!]!
}

type Mutation {
  createArticle(input: CreateArticleInput!): Article!
  addComment(articleId: ID!, input: AddCommentInput!): Comment
}

input CreateArticleInput {
  title: String!
  content: String!
  userId: ID!
}

input AddCommentInput {
  userId: String!
  content: String!
}

type User {
  id: ID!
  name: String!
}

type Article {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
  createdAt: String!
}

type Comment {
  id: ID!
  content: String!
  author: User
}

In Spring Boot, this file is registered automatically as our schema definition.

And as we can see, we defined 5 things:

• queries– how a client reads data. Every GraphQL schema must support them,
• mutations– how a client modifies data,
• inputs– used to pass structured arguments to our mutations and queries,
• types– establishing the structure of data we return,
• scalars– like String, or ID (but also Int, Float, Boolean), describing returned fields.

Moreover, we can see the exclamation mark- !. In contrast to Kotlin, in GraphQL, we must explicitly define non-nullable types. Meaning, that [Comment] describes a nullable array of nullable Comment type (Array<Comment?>?), whereas [Comment!]! is a not null array with not null items.

Spring GraphQL Schema Inspection

Following, let’s rerun our application.

As a result, we should get the following in logs:

o.s.b.a.g.GraphQlAutoConfiguration: GraphQL schema inspection:
Unmapped fields: {Query=[article, articles], Mutation=[createArticle, addComment]}
Unmapped registrations: {}
Unmapped arguments: {}
Skipped types: []

As we can see, Spring Boot verifies the schema we defined every time we start the application. And the above message simply says that we do not have handler methods for our definition.

Let’s fix that then 😉

Create Models

As the next step, let’s add Kotlin data classes to our Spring Boot project. They will be later used to serialize and deserialize data defined in our GraphQL schema.

To do so, let’s add the Models.kt:

data class User(
    val id: String,
    val name: String,
)
data class Article(
    val id: String,
    val title: String,
    val content: String,
    val authorId: String,
    val createdAt: String,
)
data class Comment(
    val id: String,
    val content: String,
    val articleId: String,
    val userId: String,
)
data class CreateArticleInput(
    val title: String,
    val content: String,
    val userId: String,
)
data class AddCommentInput(
    val content: String,
    val userId: String,
)

As we can see, nothing spectacular here. The only interesting fact is that the ID is serialized in the same way as a String.

QueryMapping as suspend fun

Following, let’s learn how the Spring for GraphQL works with Kotlin coroutines.

According to the documentation:

Kotlin coroutine and Flow are adapted to Mono and Flux.

Which means that whenever we use the Spring WebFlux, Spring automatically converts our suspended functions Mono and functions that return Flow to Flux .

Implement Article Service

Before we head to the GraphQL part, let’s make some small preparations.

Let’s insert the ArticleService:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
}

As we can see, we use my favorite, in-memory database called mutable list (😉) and expose findArticleById – a suspended function.

This function will either find the desired article by ID or return a null value.

Add ArticleController

With that done, let’s add the ArticleController:

@Controller
class ArticleController(
    private val articleService: ArticleService,
) {
    @QueryMapping
    suspend fun article(@Argument id: String): Article? =
        articleService.findArticleById(id)
}

As we can see, thanks to the Spring GraphQL, we can leverage the annotation-based approach.

Firstly, we must annotate our class with the @Controller annotation. Then, all the methods inside it annotated with @SchemaMapping annotation will become handlers.

And @QueryMapping, @MutationMapping, or @SubscriptionMapping are nothing else than meta annotations (annotated with @SchemaMapping). This way, we achieve a more readable code.

Additionally, in Spring, we use the @Argument annotation to bind GraphQL input arguments to our Kotlin instances.

Enable GraphiQL & Test

Nextly, let’s turn on the GraphiQL– the IDE for testing GraphQL APIs (like Postman, Bruno, or Insomnia).

To do so, let’s navigate to the resources directory and change the application.properties into the application.yaml file:

spring:
  application:
    name: graphsandbox
  graphql:
    graphiql:
      enabled: true

Then, let’s open up the browser, go to http://localhost:8080/graphiql, and put the following:

query SomeRandomQuery {
  article(id: "article-id-1") {
    id
    title
  }
}

As we can see, the query name is up to us, but inside it, we must define which of the “exposed” queries we would like to use. As the input parameter, we pass the String value- article-id-1– and lastly, we define what fields we would like to get in response (that’s what the whole GraphQL is a about, right?😉).

So, as the next step, let’s run the query and check out the result:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f337f3f3-5",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "article"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "article": null
  }
}

Unfortunately, that is not what we expected.

Moreover, when we check out logs, we should see this:

s.g.e.ExceptionResolversExceptionHandler : Unresolved NoClassDefFoundError for executionId f337f3f3-5
java.lang.NoClassDefFoundError: org/springframework/data/util/KotlinReflectionUtils
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.invokeSuspendingFunction(InvocableHandlerMethodSupport.java:141) ~[spring-graphql-1.3.4.jar:1.3.4]
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.doInvoke(InvocableHandlerMethodSupport.java:108) ~[spring-graphql-1.3.4.jar:1.3.4]

Fix Spring GraphQL Coroutines Issue

As we could see, the issue is caused by the missing dependency, and we can easily fix that.

To do so, let’s open up the build.gradle.kts and add the following dependency:

implementation("org.springframework.data:spring-data-commons")

Then, let’s sync the gradle project and rerun the application.

After we run the test again, we should see the following:

{
  "data": {
    "article": {
      "id": "article-id-1",
      "title": "article-title-1"
    }
  }
}

Splendid! Everything works perfectly fine😉

Spring GraphQL with Kotlin Flow

With that done, let’s learn how to work with Kotlin Flow and Spring GraphQL.

As the first step, let’s insert a new function to our ArticleService:

fun findAllArticles(): Flow<Article> = articles.asFlow()

This way, we produce a cold flow from our list of articles.

Then, let’s add a new handler:

@QueryMapping
fun articles(): Flow<Article> =
    articleService.findAllArticles()

Nothing new this time. Just like previously, we add a new function marked with @QueryMapping.

When we run the following query in GraphiQL:

query AnotherOne {
  articles {
    id
    title
    createdAt
  }
}

We should see the exact result:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-2",
        "title": "article-title-2",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-3",
        "title": "article-title-3",
        "createdAt": "2025-04-12T13:06:29.142469200"
      }
    ]
  }
}

@SchemaMapping

One of the greatest thing in GraphQL is the possibility to return the related data in one, single query. And if you remember our schema definition, our API should allow us to do that.

To be more specific, each article can have the author, multiple comments, and each comment also has its author.

But when we test that functionality right now:

query AnotherOne {
  articles {
    id
    title
    createdAt
    author {
      id
      name
    }
    
    comments {
      id
      content
      author {
        name
      }
    }
  }
}

The only thing we will get in response will be a looooong list of errors:

{
  "errors": [
    {
      "message": "The field at path '/articles[0]/author' was declared as a non null type, but the code involved in retrieving data has wrongly returned a null value.  The graphql specification requires that the parent field be set to null, or if that is non nullable that it bubble up null to its parent and so on. The non-nullable type is 'User' within parent type 'Article'",
      "path": [
        "articles",
        0,
        "author"
      ],
      "extensions": {
        "classification": "NullValueInNonNullableField"
      }
    }
... other errors

Of course, with Spring we can easily fix it, but we will need small preparation first.

Update Service

Firstly, let’s get back to our service and update it:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    private val users = mutableListOf(
        User(id = "user-id-1", name = "user-name-1"),
        User(id = "user-id-2", name = "user-name-2"),
        User(id = "user-id-3", name = "user-name-3"),
    )
    private val comments = mutableListOf(
        Comment(id = "comment-id-1", content = "comment-content-1", articleId = "article-id-1", userId = "user-id-3"),
        Comment(id = "comment-id-2", content = "comment-content-2", articleId = "article-id-2", userId = "user-id-3"),
        Comment(id = "comment-id-3", content = "comment-content-3", articleId = "article-id-2", userId = "user-id-2"),
        Comment(id = "comment-id-4", content = "comment-content-4", articleId = "article-id-3", userId = "user-id-3"),
    )
    
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
    fun findAllArticles(): Flow<Article> = articles.asFlow()
    suspend fun findUserById(id: String): User? {
        delay(100)
        return users.firstOrNull { it.id == id }
    }
    fun findCommentsByArticleId(id: String): Flow<Comment> =
        comments.filter { it.articleId == id }.asFlow()
}

As we can see, we added two more “tables” along with simple functions to obtain data from them.

Update @Controller

Then, let’s update our controller class:

@SchemaMapping
suspend fun author(article: Article): User =
    articleService.findUserById(article.authorId)!!
@SchemaMapping
suspend fun author(comment: Comment): User =
    articleService.findUserById(comment.userId)!!
@SchemaMapping
fun comments(article: Article): Flow<Comment> =
    articleService.findCommentsByArticleId(article.id)

As we can see, this time we leverage the @SchemaMapping annotation for our handlers. Pretty similar to what we did already.

The interesting part here is the parameters. Every handler takes the parent type as an argument. Meaning, that for the article -> author parent-child relationship, we define the function that takes the article instance as an argument. And that’s it!

Of course, please the double exclamation (!!) should not land in the real, production-ready code😉

Anyway, when we rerun our test now, we will see the following:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:21:17.584507600",
        "author": {
          "id": "user-id-2",
          "name": "user-name-2"
        },
        "comments": [
          {
            "id": "comment-id-1",
            "content": "comment-content-1",
            "author": {
              "name": "user-name-3"
            }
          }
        ]
      }
... more thingies 

And that’s what we expected. Awesome!

GraphQL Mutations

When we run the application right now, we see that we still miss two things that we defined- mutations.

So, before we add a new handler, let’s implement the following function in our service:

suspend fun createArticle(input: CreateArticleInput): Article {
    delay(100)
    return Article(
        id = UUID.randomUUID().toString(),
        title = input.title,
        content = input.content,
        authorId = input.userId,
        createdAt = LocalDateTime.now().toString(),
    ).also { articles.add(it) }
}

As can be seen, we take the input, create a new Article instance, and insert that to the list.

With Kotlin also ,we can return at the same time the created instance and achieve a slightly cleaner code. To be even fancier, we could use a reference here: .also(articles::add) 😉

Then, let’s add the appropriate handler to our controller:

@MutationMapping
suspend fun createArticle(@Argument input: CreateArticleInput): Article =
    articleService.createArticle(input)

As we can see, just like with @QueryMapping, this time, we mark the handler with @MutationMapping and our argument with @Argument. Nothing else is necessary to make our mutation work.

So, given that, let’s rerun the app and test our functionality:

mutation someMutation {
  createArticle(
    input: {
      title: "Awesome codersee Kotlin article", 
      content: "Some content", 
      userId: "user-id-3"
    }
  ) {
    id
    title
    content
    author {
      id
      name
    }
  }
}

As a result, we should get the following:

{
  "data": {
    "createArticle": {
      "id": "0e51a902-835b-4e55-9b4a-f2dccd242ea7",
      "title": "Awesome codersee Kotlin article",
      "content": "Some content",
      "author": {
        "id": "user-id-3",
        "name": "user-name-3"
      }
    }
  }
}

Wonderful! We can see that with GraphQL mutations, we can not only create/modify things on our server. With this one query, we can also retrieve the data and the dependent objects😮

Error Handling in Spring GraphQL

As the last step, let’s add one more mutation to learn more about error handling.

First, let’s add the new custom exception ot our codebase in Models.kt:

data class GenericNotFound(val msg: String) : RuntimeException(msg)

Then, let’s implement the following function in ArticleService:

suspend fun addComment(id: String, input: AddCommentInput): Comment {
        delay(100)
        users.firstOrNull { it.id == input.userId }
            ?: throw GenericNotFound("User not found")
        return articles.firstOrNull { it.id == id }
            ?.let {
                Comment(
                    id = UUID.randomUUID().toString(),
                    articleId = id,
                    content = input.content,
                    userId = input.userId,
                ).also { comments.add(it) }
            }
            ?: throw GenericNotFound("Article not found")
    }

This time, we can see a more production-ready code.

If we want to add a comment to the article, we must first check if both the desired author and article exist, right?

If that is not the case, then we throw our custom exception.

Following, let’s add a new mutation handler:

@MutationMapping
suspend fun addComment(
    @Argument id: String,
    @Argument input: AddCommentInput,
): Comment =
    articleService.addComment(id, input)

Now, when we rerun the app and execute the following test:

mutation anotherMutation {
  addComment(
    articleId: "non-existing"
    input: {userId: "user-id-1", content: "My comment"}
  ) {
    id
    content
  }
}

We will see the following error:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f62a4c7e-1",
      "locations": [
        {
          "line": 52,
          "column": 3
        }
      ],
      "path": [
        "addComment"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

And this is not what we wanted, right?

GraphQlExceptionHandler and ControllerAdvice

One of the solutions we can have in such a situation is a combination of ControllerAdvice and GraphQlExceptionHandler.

If you would like to learn more about ControllerAdvice and RestControllerAdvice, then check out my other article.

So, as the next step, let’s add the GlobalExceptionHandler class to the project:

@ControllerAdvice
class GlobalExceptionHandler {
    @GraphQlExceptionHandler
    fun handleGenericNotFound(ex: GenericNotFound): GraphQLError =
        GraphQLError.newError()
            .errorType(ErrorType.DataFetchingException)
            .message(ex.msg)
            .build()
}

As we can see, inside it, we implement a function that takes the GenericNotFound as an argument. This way, whenever our custom exception is thrown, Spring will return the GraphQLError instance with our config instead.

As a result, when we retest the application, we should get the following JSON:

{
  "errors": [
    {
      "message": "Article not found",
      "locations": [],
      "extensions": {
        "classification": "DataFetchingException"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

Spring GraphQL with Kotlin Coroutines Summary

And that’s all for this article on how to work with Kotlin coroutines and Flows in the Spring Boot GraphQL project.

As always, you can find the source code in my GitHub repostory.

The post Spring for GraphQL with Kotlin Coroutines appeared first on Codersee blog- Kotlin on the backend.

In my previous article, I’ve shown you how to create a simple GraphQL Spring Boot project using GraphQL schema files. This time, I would like to teach you another approach- the GraphQL SPQR (GraphQL Schema Publisher & Query Resolver).

To put it simply, GraphQL SPQR dynamically generates a schema from the source code. With this approach, we don’t need to define *.graphqls files anymore, but it will require us to add some additional configuration to the project.

2. Imports

Just like in the previous article, we will start with the imports. However, this time the graphql-java-tools dependency will be replaced by the SPQR:

implementation("org.springframework.boot:spring-boot-starter-web")
implementation("com.graphql-java:graphql-spring-boot-starter:5.0.2")
implementation("com.graphql-java:graphiql-spring-boot-starter:5.0.2")
implementation("io.leangen.graphql:spqr:0.10.1")

3. Create Models

As the next step, let’s define our POJOs.

Let’s start by adding a Company class with 4 simple properties:

class Company(
    val id: Long,
    val name: String,
    val address: String,
    val zipCode: String
)

Nextly, let’s implement the Employee class just like below:

class Employee(
    val id: Long,
    val firstName: String,
    val lastName: String,
    val status: EmployeeStatus,
    val company: Company
)

enum class EmployeeStatus {
    ACTIVE, RETIRED
}

4. Create Repositories

As the third step, we need to implement the logic responsible for data management. To keep this article as simple as possible, we won’t be connecting to any external data source (anyway, this architecture might be a great entry point for further development).

4.1. Implement CompanyRepository

Firstly, let’s create the CompanyRepository class and annotate it with @Component:

@Component
class CompanyRepository {

    private val companyId = AtomicLong(4)

    private val companies = mutableSetOf(
        Company(1, "Company One", "Address 1", "10001"),
        Company(2, "Company Two", "Address 2", "10002"),
        Company(3, "Company Three", "Address 3", "10003"),
        Company(4, "Company Four", "Address 4", "10004")
    )
}

CompanyRepository contains two properties: companyId– an atomic variable, which will be used to generate identifiers for companies; and companies– a set containing predefined objects.

Nextly, let’s add functions responsible for searching, creating, and deleting companies:

fun findAll(): Set = companies

fun findById(companyId: Long): Company =
    companies.find { it.id == companyId }
        ?: throw RuntimeException("Company with id [$companyId] could not be found.")

fun create(name: String, address: String, zipCode: String): Company {
    val company = Company(
        id = companyId.incrementAndGet(),
        name = name,
        address = address,
        zipCode = zipCode
    )

    companies.add(company)
    return company
}

fun delete(id: Long): Boolean =
    companies.removeIf { it.id == id }

4.2. Implement EmployeeRepository

With that being done, we can create the EmployeeRepository as follows:

@Component
class EmployeeRepository(
    private val companyRepository: CompanyRepository
) {

    val employerId = AtomicLong(3)

    val employees = mutableSetOf(
        Employee(1, "John", "Doe", EmployeeStatus.ACTIVE, companyRepository.findById(1)),
        Employee(2, "Adam", "Nowak", EmployeeStatus.ACTIVE, companyRepository.findById(2)),
        Employee(3, "Stan", "Bar", EmployeeStatus.RETIRED, companyRepository.findById(3))
    )
}

Similarly, the EmployeeRepository will contain 4 simple functions:

fun findAll(): Set = employees

fun findById(employeeId: Long) =
    employees.find { it.id == employeeId }
        ?: throw RuntimeException("Employee with id [$employeeId] could not be found.")

fun create(
    firstName: String,
    lastName: String,
    status: EmployeeStatus,
    companyId: Long
): Employee {
    val company = companyRepository.findById(companyId)

    val employee = Employee(
        id = employerId.incrementAndGet(),
        firstName = firstName,
        lastName = lastName,
        status = status,
        company = company
    )

    employees.add(employee)
    return employee
}

fun delete(id: Long): Boolean =
    employees.removeIf { it.id == id }

5. Define Queries

In simple terms, Queries are responsible for retrieving data from our server. You might consider it something, like GET requests in REST APIs.

Let’s start by creating the CompanyQuery class as follows:

@Component
class CompanyQuery(
    private val companyRepository: CompanyRepository
) {

    @GraphQLQuery(name = "companies")
    fun companies(): Set<Company> =
        companyRepository.findAll()

    @GraphQLQuery(name = "companyById")
    fun companyById(id: Long): Company =
        companyRepository.findById(id)
}

As you can see, it’s just a simple Spring Boot component. However, if we want to expose our functions, we need to annotate them with @GraphQLQuery. Moreover, query and function names do not need to match at all- we can name them independently.

Similarly, let’s create the EmployeeQuery class:

@Component
class EmployeeQuery(
    private val employeeRepository: EmployeeRepository
) {

    @GraphQLQuery(name = "employees")
    fun employees(): Set<Employee> =
        employeeRepository.findAll()

    @GraphQLQuery(name = "employeeById")
    fun employeeById(id: Long): Employee =
        employeeRepository.findById(id)
}

6. Create Mutations

Our next step will be the implementation of Mutations. They work in a similar way, but we use them to modify the data (you might consider them as the equivalent of POST/PUT/PATCH/DELETE handlers).

Let’s start with creating the CompanyMutation class:

@Component
class CompanyMutation(
    private val companyRepository: CompanyRepository
) {

    @GraphQLMutation(name = "newCompany")
    fun newCompany(name: String, address: String, zipCode: String): Company =
        companyRepository.create(name, address, zipCode)

    @GraphQLMutation(name = "deleteCompany")
    fun deleteCompany(id: Long): Boolean =
        companyRepository.delete(id)
}

Please notice, that this time we’ve used the @GraphQLMutation annotation instead.

Finally, let’s implement the EmployeeMutation in a similar manner:

@Component
class EmployeeMutation(
    private val employeeRepository: EmployeeRepository
) {

    @GraphQLMutation(name = "newEmployee")
    fun newEmployee(
        firstName: String,
        lastName: String,
        status: EmployeeStatus,
        companyId: Long
    ): Employee =
        employeeRepository.create(firstName, lastName, status, companyId)

    @GraphQLMutation(name = "deleteEmployee")
    fun deleteEmployee(id: Long): Boolean =
        employeeRepository.delete(id)
}

7. Prepare Configuration File

After all the above is finished, we need to implement a schema generator and configure the GraphQL bean.

Let’s start by adding the GraphQLConfig class with the prepareGraphQLSchema function:

@Configuration
class GraphQLConfig {
    private fun prepareGraphQLSchema(
        companyQuery: CompanyQuery, employeeQuery: EmployeeQuery,
        companyMutation: CompanyMutation, employeeMutation: EmployeeMutation
    ): GraphQLSchema =
        GraphQLSchemaGenerator()
            .withResolverBuilders(
                AnnotatedResolverBuilder(),
                PublicResolverBuilder("com.codersee.graphqlspqr")
            )
            .withOperationsFromSingletons(companyQuery, employeeQuery, companyMutation, employeeMutation)
            .withValueMapperFactory(JacksonValueMapperFactory())
            .generate()
}

Please notice, that the String passed to the PublicResolverBuilder constructor has to reflect the package structure of your project.

Lastly, let’s set up our GraphQL bean using the already implemented schema:

@Bean
fun graphQL(
    companyQuery: CompanyQuery, employeeQuery: EmployeeQuery,
    companyMutation: CompanyMutation, employeeMutation: EmployeeMutation
): GraphQL {
    val schema = prepareGraphQLSchema(companyQuery, employeeQuery, companyMutation, employeeMutation)

    return GraphQL.newGraphQL(schema)
        .queryExecutionStrategy(AsyncExecutionStrategy())
        .instrumentation(
            ChainedInstrumentation(
                listOf(
                    MaxQueryComplexityInstrumentation(100),
                    MaxQueryDepthInstrumentation(10)
                )
            )
        )
        .build()
}

As you can see, besides the execution strategy, we’ve configured the maximum complexity and depth values for our queries and mutations.

8. Implement the Controller

As the last step, we need to create the entry point for our queries.

Let’s create a class called GraphQLController. Additionally, let’s inject the GraphQL bean configured in the previous step:

@RestController
class GraphQLController(
    private val graphQL: GraphQL
) {

    @PostMapping("/graphql")
    @ResponseBody
    fun execute(@RequestBody request: Map<String, String>): ExecutionResult {
        return graphQL
            .execute(
                request["query"].toString()
            )
    }
}

As you can see, the only function we need to implement here is the execute, which will be responsible for handling all the GraphQL requests.

9. Testing

Finally, we can run the application and test it. Just like in the previous article, we will use the GraphiQL– a dedicated GUI for communicating with GraphQL servers.

In the beginning, we’ve added the GraphiQL Spring Boot Starter dependency, which allows us to run its web-based version under the /graphiql endpoint. However, you can always download it’s Electron-based wrapper here.

9.1. Test Queries

After starting the application, let’s head to the http://localhost:8080/graphiql endpoint and run the following query:

query {
  employees {
    id
    firstName
    lastName
    status
    company {
      name
    }
  }
}

As you can see, the query structure allows us to define, which fields we would like to fetch. I highly suggest you check out different combinations and see what will be the results. As a result of the above query, we should see the following output:

{
  "data": {
    "employees": [
      {
        "id": "1",
        "firstName": "John",
        "lastName": "Doe",
        "status": "ACTIVE",
        "company": {
          "name": "Company One"
        }
      }
...

Nextly, let’s try to find the employee by id:

query {
  employeeById(id: 1) {
    id
    firstName
    lastName
    status
    company {
      id
      name
    }
  }
}

# Result:

{
  "data": {
    "employeeById": {
      "id": "1",
      "firstName": "John",
      "lastName": "Doe",
      "status": "ACTIVE",
      "company": {
        "id": "1",
        "name": "Company One"
      }
    }
  }
}

Similarly, we can test company queries:

query {
  companies {
    id
    name
    address
    zipCode
  }
}

# Result:

{
  "data": {
    "companies": [
      {
        "id": "1",
        "name": "Company One",
        "address": "Address 1",
        "zipCode": "10001"
      },
...

query {
  companyById(id: 1) {
    id
    name
    address
    zipCode
  }
}

# Result:

{
  "data": {
    "companyById": {
      "id": "1",
      "name": "Company One",
      "address": "Address 1",
      "zipCode": "10001"
    }
  }
}

9.1. Test Mutations

Testing mutations is quite similar to queries. The only difference is the usage of a mutation keyword:

mutation {
  newCompany(name: "New", address: "Address new", zipCode: "10201") {
    id
    name
    address
    zipCode
  }
}

This time, a new company will be created, and the following data will be returned:

{
  "data": {
    "newCompany": {
      "id": "5",
      "name": "New",
      "address": "Address new",
      "zipCode": "10201"
    }
  }
}

Similarly, we can create a new employee:

mutation {
  newEmployee(firstName: "Piotr", lastName:"Wolak", status: ACTIVE, companyId: 2) {
    id
    firstName
    lastName
    status
    company {
      id
      name
    }
  }
}

# Result:

{
  "data": {
    "newEmployee": {
      "id": "4",
      "firstName": "Piotr",
      "lastName": "Wolak",
      "status": "ACTIVE",
      "company": {
        "id": "2",
        "name": "Company Two"
      }
    }
  }
}

Finally, let’s test delete mutations:

{
  "data": {
    "deleteCompany": true
  }
}

# Result:

{
  "data": {
    "deleteCompany": true
  }
}

mutation {
  deleteEmployee(id: 1)
}

# Result:

{
  "data": {
    "deleteEmployee": true
  }
}

9. Conclusion

And that would be all for this tutorial. I really hope that this article helped you to get a better understanding of how to create a GraphQL SPQR project with Spring Boot and Kotlin.

As always, you can find the working source code in our GitHub repository.

If you would like to ask about anything or share any feedback with me, I would be more than happy to hear from you. You can always contact me via fan page, group, or a contact form.

The post GraphQL SPQR with Spring Boot and Kotlin appeared first on Codersee blog- Kotlin on the backend.

In this step by step tutorial, I would like to show you how to use GraphQL with Spring Boot and Kotlin. Additionally, we will learn how to test with GraphiQL– a dedicated GUI for editing and testing GraphQL queries and mutations.

In simple words, GraphQL is a query language for APIs that provides a more flexible alternative to REST. It allows clients to define the structure of the desired data, and the same structure of the data is returned from the server, therefore preventing large amounts of data from being returned. It was developed internally by Facebook in 2012 and open-sourced in 2015.

2. Imports

As the first step, let’s add the necessary imports to our project:

implementation("org.springframework.boot:spring-boot-starter-web")
implementation("com.graphql-java:graphql-spring-boot-starter:5.0.2")
implementation("com.graphql-java:graphiql-spring-boot-starter:5.0.2")
implementation("com.graphql-java:graphql-java-tools:5.2.4")

As you can see, besides Spring Boot starters, we’ve added the GraphQL Java Tools library. It allows us to use the GraphQL schema language to build our graphql-java schema. Additionally, it parses the given GraphQL schema and allows us to BYOO (bring your own object) to fill in the implementations.

3. Create Models

As the next step, let’s implement our models. In this tutorial, we will implement a simple CRUD service for employees’ management.

Let’s start by adding a Company class with 4 simple properties:

class Company(
    val id: Long,
    val name: String,
    val address: String,
    val zipCode: String
)

As the next step, let’s implement the Employee class:

class Employee(
    val id: Long,
    val firstName: String,
    val lastName: String,
    val status: EmployeeStatus,
    val company: Company
)

enum class EmployeeStatus {
    ACTIVE, RETIRED
}

Besides the class, we’ve also added the EmployeeStatus enum, which will be used as one of the properties of Employee. Additionally, each employee will have a company property indicating the associated company.

4. Create Repositories

Nextly, let’s create repositories responsible for in-memory data management.

4.1. Implement CompanyRepository

Firstly, let’s create the CompanyRepository class and annotate it with @Component:

@Component
class CompanyRepository {

    private val companyId = AtomicLong(4)

    private val companies = mutableSetOf(
        Company(1, "Company One", "Address 1", "10001"),
        Company(2, "Company Two", "Address 2", "10002"),
        Company(3, "Company Three", "Address 3", "10003"),
        Company(4, "Company Four", "Address 4", "10004")
    )
}

CompanyRepository contains two properties: companyId– an atomic variable, which will be used to generate identifiers for companies; and companies– a set containing predefined objects.

As the next step, let’s add functions responsible for searching, creating, and deleting companies:

fun findAll(): Set = companies

fun findById(companyId: Long): Company =
    companies.find { it.id == companyId }
        ?: throw RuntimeException("Company with id [$companyId] could not be found.")

fun create(name: String, address: String, zipCode: String): Company {
    val company = Company(
        id = companyId.incrementAndGet(),
        name = name,
        address = address,
        zipCode = zipCode
    )

    companies.add(company)
    return company
}

fun delete(id: Long): Boolean =
    companies.removeIf { it.id == id }

4.2. Implement EmployeeRepository

With that being done, we can create the EmployeeRepository as follows:

@Component
class EmployeeRepository(
    private val companyRepository: CompanyRepository
) {

    val employerId = AtomicLong(3)

    val employees = mutableSetOf(
        Employee(1, "John", "Doe", EmployeeStatus.ACTIVE, companyRepository.findById(1)),
        Employee(2, "Adam", "Nowak", EmployeeStatus.ACTIVE, companyRepository.findById(2)),
        Employee(3, "Stan", "Bar", EmployeeStatus.RETIRED, companyRepository.findById(3))
    )
}

Similarly, the EmployeeRepository will have 4 simple functions:

fun findAll(): Set = employees

fun findById(employeeId: Long) =
    employees.find { it.id == employeeId }
        ?: throw RuntimeException("Employee with id [$employeeId] could not be found.")

fun create(
    firstName: String,
    lastName: String,
    status: EmployeeStatus,
    companyId: Long
): Employee {
    val company = companyRepository.findById(companyId)

    val employee = Employee(
        id = employerId.incrementAndGet(),
        firstName = firstName,
        lastName = lastName,
        status = status,
        company = company
    )

    employees.add(employee)
    return employee
}

fun delete(id: Long): Boolean =
    employees.removeIf { it.id == id }

5. Define GraphQL Schema

After we’ve implemented our models and repositories, we can start defining the schema. In simple terms, a schema is a contract between the client and the server describing the structure of the data and how the data might be operated.

For the purpose of this tutorial, let’s focus on the 4 types, we will be using:

• Object Types– the most basic components, which represent a kind of objects we can fetch from our service (classes in our example)
• Enums– a special kind of scalar values restricted to a particular set of values
• Queries– every GraphQL service needs to have a Query. To put it simply, queries are used to describe how to read, or fetch values
• Mutations– work in a similar way, as queries and are used to modify a server-side data

If you would like to learn more about the GraphQL Schema, please refer to the official documentation.

5.1. Describe Company Schema

Let’s start with the definition of company schema. Let’s create a company.graphqls file and put it under the ./src/main/resources/ directory:

type Company {
    id: ID!
    name: String!
    address: String!
    zipCode: String!
}

type Query {
    companies: [Company]
    companyById(id: ID!) : Company
}

type Mutation {
    newCompany(name: String!, address: String!, zipCode: String!) : Company!
    deleteCompany(id: ID!) : Boolean
}

In this simple file, we’ve declared three types:

• The Company type– which will be associated with the Company entity, we’ve created earlier
• The Query type– containing two queries
• The Mutation type– describing mutations for company creation and removal

5.2. Describe Employee Schema

As the next step, let’s create an employee.graphqls file:

type Employee {
    id: ID!
    firstName: String!
    lastName: String!
    status: EmployeeStatus!
    company: Company!
}

enum EmployeeStatus{
    ACTIVE, RETIRED
}

extend type Query {
    employees: [Employee]
    employeeById(id: ID!) : Employee
}

extend type Mutation {
    newEmployee(firstName: String!, lastName: String!, status: EmployeeStatus!, companyId: ID!) : Employee!
    deleteEmployee(id: ID!) : Boolean
}

This file is pretty similar to the previous one, but we’ve also added the Enum type here. Additionally, please notice the extend keyword- we have to place it in order to extend the Mutation and Query declared in another file.

6. Create Queries Resolvers

After we’ve defined the schema, we can start adding the code responsible for data manipulation. Let’s start by adding the CompanyQuery class:

@Component
class CompanyQuery(
    private val companyRepository: CompanyRepository
) : GraphQLQueryResolver {

    fun companies(): Set =
        companyRepository.findAll()

    fun companyById(id: Long): Company =
        companyRepository.findById(id)
}

Please notice two important things here. Firstly, the CompanyQuery class implements the GraphQLQueryResolver, which is a markup interface provided by the GraphQL dependency. Secondly, public functions need to match the schema in order to be resolved correctly.

Similarly, let’s implement the EmployeeQuery class:

@Component
class EmployeeQuery(
    private val employeeRepository: EmployeeRepository
) : GraphQLQueryResolver {

    fun employees(): Set =
        employeeRepository.findAll()

    fun employeeById(id: Long): Employee =
        employeeRepository.findById(id)
}

7. Implement Mutations Resolvers

In order for our application to be fully functional, we need to add the resolvers for our mutations. As the first step, let’s add the CompanyMutation class:

@Component
class CompanyMutation(
    private val companyRepository: CompanyRepository
) : GraphQLMutationResolver {

    fun newCompany(name: String, address: String, zipCode: String): Company =
        companyRepository.create(name, address, zipCode)

    fun deleteCompany(id: Long): Boolean =
        companyRepository.delete(id)
}

Just like in Queries resolvers, public functions need to match the structure from the defined schema. The only difference here is that we’ve implemented the GraphQLMutationResolver interface.

Finally, we can add the last class to our project which will be responsible for the employee mutations:

@Component
class EmployeeMutation(
    private val employeeRepository: EmployeeRepository
) : GraphQLMutationResolver {

    fun newEmployee(
        firstName: String,
        lastName: String,
        status: EmployeeStatus,
        companyId: Long
    ): Employee =
        employeeRepository.create(firstName, lastName, status, companyId)

    fun deleteEmployee(id: Long): Boolean =
        employeeRepository.delete(id)

}

8. Testing

Finally, we can run the application and test it. In this article, I would like to show you the tool called GraphiQL– a dedicated GUI for communicating with GraphQL servers.

In the beginning, we’ve added the GraphiQL Spring Boot Starter dependency, which allows us to run its web-based version under the /graphiql endpoint. However, you can always download it’s Electron-based wrapper here.

8.1. Test Queries

After starting the application, let’s head to the http://localhost:8080/graphiql endpoint and run the following query:

query {
  employees {
    id
    firstName
    lastName
    status
    company {
      name
    }
  }
}

As you can see, the query structure allows us to define, which fields we would like to fetch. I highly suggest you check out different combinations and see what will be the results. As a result of the above query, we should see the following output:

{
  "data": {
    "employees": [
      {
        "id": "1",
        "firstName": "John",
        "lastName": "Doe",
        "status": "ACTIVE",
        "company": {
          "name": "Company One"
        }
      }
...

Nextly, let’s try to find the employee by id:

query {
  employeeById(id: 1) {
    id
    firstName
    lastName
    status
    company {
      id
      name
    }
  }
}

# Result:

{
  "data": {
    "employeeById": {
      "id": "1",
      "firstName": "John",
      "lastName": "Doe",
      "status": "ACTIVE",
      "company": {
        "id": "1",
        "name": "Company One"
      }
    }
  }
}

Similarly, we can test company queries:

query {
  companies {
    id
    name
    address
    zipCode
  }
}

# Result:

{
  "data": {
    "companies": [
      {
        "id": "1",
        "name": "Company One",
        "address": "Address 1",
        "zipCode": "10001"
      },
...

query {
  companyById(id: 1) {
    id
    name
    address
    zipCode
  }
}

# Result:

{
  "data": {
    "companyById": {
      "id": "1",
      "name": "Company One",
      "address": "Address 1",
      "zipCode": "10001"
    }
  }
}

8.1. Test Mutations

Testing mutations is quite similar to queries. The only difference is the usage of a mutation keyword:

mutation {
  newCompany(name: "New", address: "Address new", zipCode: "10201") {
    id
    name
    address
    zipCode
  }
}

This time, a new company will be created, and the following data will be returned:

{
  "data": {
    "newCompany": {
      "id": "5",
      "name": "New",
      "address": "Address new",
      "zipCode": "10201"
    }
  }
}

Similarly, we can create a new employee:

mutation {
  newEmployee(firstName: "Piotr", lastName:"Wolak", status: ACTIVE, companyId: 2) {
    id
    firstName
    lastName
    status
    company {
      id
      name
    }
  }
}

# Result:

{
  "data": {
    "newEmployee": {
      "id": "4",
      "firstName": "Piotr",
      "lastName": "Wolak",
      "status": "ACTIVE",
      "company": {
        "id": "2",
        "name": "Company Two"
      }
    }
  }
}

Finally, let’s test delete mutations:

{
  "data": {
    "deleteCompany": true
  }
}

# Result:

{
  "data": {
    "deleteCompany": true
  }
}

mutation {
  deleteEmployee(id: 1)
}

# Result:

{
  "data": {
    "deleteEmployee": true
  }
}

9. Conclusion

And that would be all for this tutorial. I really hope that you have learned how to use GraphQL with Spring Boot and Kotlin and that testing with GraphiQL will be a piece of cake for you.

For the source code, please refer to this GitHub repository.

If you would like to ask about anything or share any feedback with me, I would be more than happy to hear from you. You can always contact me via fan page, group, or a contact form.

The post Introduction to GraphQL with Spring Boot and Kotlin appeared first on Codersee blog- Kotlin on the backend.