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.

I can guarantee that you will benefit from this tutorial regardless of whether you saw previous articles about S3Client or S3Template, or not. But, I definitely encourage you to take a look at them, too:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 Spring Boot with Kotlin, AWS S3, and S3Template
• #3 (This article)

Video Tutorial

If you prefer video content, then check out my video that covers all three articles:

If you find this content useful, please leave a subscription 🙂

Prerequisites

Before heading to the guide, I just wanted to emphasize that today we will be working with Testcontainers. And this means that we must have a supported Docker environment.

So, if you do not have Docker configured on your local and want to follow this article, please check out their documentation.

Of course, you must have Java, IDE, and Spring Boot project too, but I believe this is quite obvious 😉

Testcontainers and LocalStack

Lastly, I would like to say a few words about the Testcontainers and LocalStack, which in my opinion are a great way to test Spring Boot S3 integration (and other AWS integrations, too).

Testcontainers

Testcontainers is a library for providing throwaway, lightweight instances of Docker containers. They are an excellent approach whenever need to test behavior dependent on external services, like AWS, or some external databases.

Long story short, instead of mocking, or manual set up of some test environment, we define test dependencies as code. Then, we can run our test code and disposable containers will be started and deleted after they finish.

Let’s take a look at the example from Spring Boot docs:

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

  @Test
  fun myTest() {
    // ...
  }

  companion object {
    @Container
    @JvmStatic
    val neo4j = Neo4jContainer("neo4j:5");
  }
}

The above code runs a Neo4j docker container before the tests. Of course, this is just an example, so most of the time, we will need to add some more config.

Nevertheless, we can clearly see that this Testcontainers JUnit integration allows us to achieve our goal in an easy and neat manner.

Localstack

Localstack, on the other hand, is a cloud service emulator that runs in a single container. In other words, we can run AWS applications or Lambdas without connecting to the remote cloud provider.

And thanks to the Testcontainers module for LocalStack, we can test various AWS integrations with just a few lines of code.

Again, let’s take a look at the example, but this time from the LocalStack documentation:

DockerImageName localstackImage = DockerImageName.parse("localstack/localstack:3.5.0");

@Rule
public LocalStackContainer localstack = new LocalStackContainer(localstackImage)
        .withServices(S3);

You will find links to both documentation at the end of this article. But for now, let’s not distract ourselves and focus on what we came here for 😉

Configure Project

If you are following my S3 series, or you already have a Spring Boot project, then those are the necessary dependencies for us today:

testImplementation("org.springframework.boot:spring-boot-starter-webflux")
testImplementation("org.testcontainers:localstack")
testImplementation("org.springframework.boot:spring-boot-testcontainers")

As we can see, apart from LocalStack and TestContainers, we must provide the Spring Boot Starter WebFlux.

But why?

Well, this is necessary to work with WebTestClient- a client we will use to test our web servers (REST endpoints).

On the other hand, if you would like to set up a project from scratch, then please navigate to the Spring Initializr and select the following:

However, please keep in mind that LocalStack is not provided out of the box in Spring, so we must add it manually.

Moreover, as we have chosen the Spring Web, the WebFlux dependency is not present, too:

testImplementation("org.springframework.boot:spring-boot-starter-webflux")
testImplementation("org.testcontainers:localstack")

Testcontainers Singleton Approach

With all of that being done, let’s head to the practice part.

When working with Testcontainers, we can configure them in various ways:

• we can use the JUnit extension (Jupiter integration)- which allows us to use @Testcontainers and @Container annotations and makes JUnit responsible for the automatic startup and stop of containers in our tests.
• we can configure them manually in every test case,
• or, alternatively, we can use the singleton approach– in which we control containers’ lifecycle manually. But, thanks to that we can easily reuse them across multiple test classes.

Of course, these are not all approaches, and based on your needs you may want to configure Testcontainers differently. Nevertheless, in this tutorial, we will focus on the manual, reusable approach.

Introduce Base Class

Firstly, let’s introduce the LocalStackIntegrationTest:

@SpringBootTest(webEnvironment = RANDOM_PORT)
class LocalStackIntegrationTest { }

As we can see, we mark our class with @SpringBootTest – annotation necessary to run our integration tests and inject the instance of WebTestClient later in our subclasses.

Add Testcontainer

Following, let’s take a look at how to instantiate a LocalStack container:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  )
}

Right here, we create an instance of LocalStackContainer and we pass the name of a Docker image – localstack/localstack:3.7.2– to its constructor. Alternatively, if we are working only with AWS S3 Buckets service, then we can use a dedicated image- localstack:s3-latest. But personally, I am not a big fan of the latest tag, which can easily break our code.

Additionally, we put the LocalStackContainer instance in the companion object. Why? Because in the next steps, we will reference it in a function annotated with @DynamicPropertySource– and it must be static.

Note related to JUnit extension:

This is not the case here, as we want to take care of the container lifecycle manually, but, when using the Jupiter integration, containers declared as static fields will be shared between test methods. They will be started only once before any test method is executed and stopped after the last test method has executed. So, if in your case you pick the JUnit extension and don’t want that to happen, then you must not put the localstack in the companion object.

Control Testcontainer lifecycle

As we already know, with this approach we are responsible for the container lifecycle control. And although this may sound complicated, it basically means that without the extension we must start the container manually.

So the companion object after the update will look, as follows:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  ).apply {
    start()
  }
}

Basically, we use the Kotlin scope function (you can learn more about it in my Kotlin course) to invoke the start() function on the localStack instance. And as the name suggests, this function will start the container (and pull the image, if necessary).

And basically, that is all we need to do here. With the above code, the container will be started when the base class is loaded and shared across all inheriting test classes.

Of course, there is also the stop() function that we can invoke to kill and remove the container.

Nevertheless, we do not have to do it. Why? Let’s figure out.

Ryuk

Ryuk is a kind of “garbage collector” in Testcontainers.

Whenever we run integration tests, Testcontianers core starts one more container:

Long story short, this container is responsible for removing containers/networks/volumes created by our test cases. So, even if we do not clean the environment ourselves- for example with the stop() function- the Ryuk container will take care of that.

Test Properties With DynamicPropertySource

With that done, we need to update our environment configuration.

If we try to run our Spring Boot application at this point, our logic responsible for communication with Amazon S3 will try to reach the actual AWS instance. It will use the defaults, or make use of the things we configured in the application.yaml.

And this is not what we want, right? Instead, we would like to connect to the Testcontainer LocalStack instance.

In some examples, you might have seen the usage of application properties files. Nevertheless, if we want to be more flexible and make use of containers started on random ports, then the @DynamicPropertySource is our best friend here:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  ).apply {
    start()
  }

  @JvmStatic
  @DynamicPropertySource
  fun overrideProperties(registry: DynamicPropertyRegistry) {
    registry.add("spring.cloud.aws.region.static") { localStack.region }
    registry.add("spring.cloud.aws.credentials.access-key") { localStack.accessKey }
    registry.add("spring.cloud.aws.credentials.secret-key") { localStack.secretKey }
    registry.add("spring.cloud.aws.s3.endpoint") { localStack.getEndpointOverride(S3).toString() }
  }

}

Thanks to that annotation, we can dynamically provide values to our test environment based on the LocalStack instance.

Of course, we must remember that methods annotated with @DynamicPropertySource must be static! And that’s why we use it with the @JvmStatic annotation.

Utilize LocalStack AWS CLI

At this point, we have our base class ready, but before we head to the tests, I would like to show you the LocalStack AWS CLI and why and how to use it.

As the first step, let’s create the util package and add the LocalStackUtil.kt file:

import org.testcontainers.containers.localstack.LocalStackContainer

fun LocalStackContainer.createBucket(bucketName: String) {
  this.execInContainer("awslocal", "s3api", "create-bucket", "--bucket", bucketName)
}

fun LocalStackContainer.deleteBucket(bucketName: String) {
  this.execInContainer("awslocal", "s3api", "delete-bucket", "--bucket", bucketName)
}

fun LocalStackContainer.deleteObject(bucketName: String, objectName: String) {
  this.execInContainer("awslocal", "s3api", "delete-object", "--bucket", bucketName, "--key", objectName)
}

As we can see, we introduced 3 helper extension functions that we will later use to create and delete buckets and objects. This way, we can easily clean up between the tests (we use the shared approach, right?). Moreover, it will simplify the setup process for each test case.

The above code combines the execInContainer – which will run the passed command in our running LocalStack container, just like with the docker exec, and the awslocal– a LocalStack wrapper around the AWS CLI. So, if you’ve ever been working with the AWS command line interface, then you will see that this is 1:1.

Unfortunately, we must provide the command as a separate String value, because otherwise, we will end up with:

OCI runtime exec failed: exec failed: container_linux.go:380: starting container process caused: exec: “awslocal s3api create-bucket –bucket bucket-1”: executable file not found in $PATH: unknown

Write Integration Test Cases

With all of that LocalStack preparation done (I know, quite a bunch of things to learn, but once you learn this, it will be a simple copy-paste), we can finally write some integration tests for our Spring Boot S3 integration.

Firstly, let’s create the controller package and put the BucketControllerIntegrationTest class:

class BucketControllerIntegrationTest(
  @Autowired private val webTestClient: WebTestClient
) : LocalStackIntegrationTest() { }

As we can see, no annotations are required. We simply extend the LocalStackIntegrationTest class and inject the WebTestClient.

Test No Buckets Exist

Nextly, let’s introduce our first test case. If we do not do anything, we expect that no buckets exist in our S3 instance:

@Test
fun `Given no existing buckets When getting list of buckets Then return an empty array`() {
  val buckets = webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(buckets)
  assertTrue(buckets.isEmpty())
}

As mentioned before, we use the WebTestClient to make a GET HTTP request to the /buckets endpoint. Then, we use a small hack with ParameterizedTypeReference– because the endpoint returns a list of Strings and we use Kotlin- and we obtain the response body.

Lastly, we have plain assertions. We verify that the response body is not null and that our S3 bucket list is empty.

Verify S3 Bucket Exists In LocalStack

Following, let’s see our helper functions in action:

@Test
fun `Given one existing bucket When getting list of buckets Then return an array with expected bucket name`() {
  val bucketName = "bucket-1"
  localStack.createBucket(bucketName)

  val expectedJson = """
    [ "Bucket #1: $bucketName" ]
  """

  webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteBucket(bucketName)
}

This time, we utilize the createBucket and make sure that the /buckets endpoint returns the expected JSON. Please note that this is another way to assert the response body.

After all, we delete the existing bucket, so it won’t affect other test cases.

Assert Bucket Created Successfully

As the next step, let’s take a look at how we can check if our endpoint responsible for creating new S3 buckets works. And I see two paths we can go here.

The first one, using the execInContainer:

@Test
fun `Given no existing buckets When creating bucket Then create bucket successfully`() {
  val bucketName = "bucket-2"
  
  webTestClient
    .post().uri("/buckets")
    .bodyValue(BucketRequest(bucketName = bucketName))
    .exchange()
    .expectStatus().isOk()
  
  val execResult = localStack.execInContainer("awslocal", "s3api", "list-buckets").stdout
  
  assertTrue(execResult.contains(bucketName))  
  localStack.deleteBucket(bucketName)
}

The important thing to mention here is that the execInContainer returns the ExecResult. And thanks to that, we can read additional info, like stdout, stderr, or exitCode.

And thanks to the stdout, we can get this JSON to verify it contains particular bucket name (or even we could parse that to an object):

{
  "Buckets": [
    {
      "Name": "bucket-2",
      "CreationDate": "2024-09-19T05:28:42.000Z"
    }
  ],
  "Owner": {
    "DisplayName": "webfile",
    "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
  }
}

Alternatively, we can use the /buckets endpoint once again, too:

@Test
fun `Given no existing buckets When creating bucket Then create bucket successfully`() {
  val bucketName = "bucket-2"

  webTestClient
    .post().uri("/buckets")
    .bodyValue(BucketRequest(bucketName = bucketName))
    .exchange()
    .expectStatus().isOk()

  val expectedJson = """
    [ "Bucket #1: $bucketName" ]
  """
  webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteBucket(bucketName)
}

Test Remaining Cases

The remaining cases of our integration test use a more or less similar approach, so I will simply copy-paste them here so that you can analyze them.

At this point, I am pretty sure you understand the general idea behind what I understand by testing of Spring Boot S3 integration with LocalStack, so I don’t see the need for explaining them one- by one:

@Test
fun `Given no objects existing in the bucket When getting objects of a bucket Then return an empty array`() {
  val bucketName = "bucket-3"
  localStack.createBucket(bucketName)

  val objects = webTestClient
    .get().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(objects)
  assertTrue(objects.isEmpty())

  localStack.deleteBucket(bucketName)
}

@Test
fun `Given no objects When creating example object Then return created object`() {
  val bucketName = "bucket-4"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expectedJson = """
    {
      "id": "123",
      "name": "Some name"
    }
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given created object When getting list of objects Then return array with one object`() {
  val bucketName = "bucket-5"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expectedJson = """
    [ $objectName ]
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()

  webTestClient
    .get().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given existing object When getting object by key Then return object content`() {
  val bucketName = "bucket-6"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expected = """
    {
      "id": "123",
      "name": "Some name"
    }
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()

  webTestClient
    .get().uri("/buckets/$bucketName/objects/$objectName")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expected)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given existing bucket with object When deleting bucket Then bucket is removed`() {
  val bucketName = "bucket-7"
  localStack.createBucket(bucketName)

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()

  webTestClient
    .delete().uri("/buckets/$bucketName")
    .exchange()
    .expectStatus().isOk()

  val buckets = webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(buckets)
  assertTrue(buckets.isEmpty())
}

Summary

And that is all for this tutorial, in which we learned how to implement integration tests for Spring Boot AWS S3 integration with LocalStack and Testcontainers.

I hope you enjoyed it and for the source code, please visit this GitHub repository.

Have a great day and see you in the next articles! 🙂

The post Test Spring Boot AWS S3 with Localstack and Testcontainers appeared first on Codersee blog- Kotlin on the backend.

Of course, I highly encourage you to take a look at other articles in this series, too:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 (This article)
• #3 Test Spring Boot AWS S3 with Localstack and Testcontainers

Video Tutorial

If you prefer video content, then check out my video that covers all three articles:

If you find this content useful, please leave a subscription 🙂

What is S3Template?

Before we get our hands dirty with the code, let’s take a second to understand better with S3Template is and how it can make our lives easier when integrating a Spring Boot app with S3.

Let me quote the S3Template documentation here:

Higher level abstraction over S3Client providing methods for the most common use cases.

So, if you have already worked with, or you have seen my previous article with S3Client, then you saw that simple operations require some boilerplate. And that is exactly what S3Template solves.

And as a note from my end, I just wanted to note S3Template handles only some subset of S3Client operations, so in our projects those two will rather coexist, instead of being each others alternatives.

AWS S3Template Operations

With all of that said, let’s get to work.

Let’s add the controller package and BucketController class to it. We will use it to expose a bunch of endpoints triggering various operations on S3 buckets and files.

When it comes to the operations- we will use the same ones as in the previous article, and as the last one, I will show you how to serialize and deserialize objects with AWS S3 and S3Template.

List All Buckets

Although the S3Template does not expose any method that would help us with this task, I wanted to mention it as we discussed it in the previous tutorial.

Additionally, this is a great example of S3Client and S3Template co-existence:

@RestController
@RequestMapping("/buckets")
class BucketController(
  private val s3Template: S3Template,
  private val s3Client: S3Client,
) {

  @GetMapping
  fun listBuckets(): List<String> {
    val response = s3Client.listBuckets()

    return response.buckets()
      .mapIndexed { index, bucket ->
        "Bucket #${index + 1}: ${bucket.name()}"
      }
  }
}

As we can see, not too much S3Template could improve here, so I bet this is the reason why it was not introduced.

New S3 Bucket

Nextly, let’s take a look at how we can create a brand new bucket:

@PostMapping
fun createBucket(@RequestBody request: BucketRequest) {
  s3Template.createBucket(request.bucketName)
}

data class BucketRequest(val bucketName: String)

As we can see, no additional request classes- the only thing we need is the bucket name.

Of course, let’s rerun our application and verify if everything is working:

curl --location --request POST 'http://localhost:8080/buckets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bucketName": "codersee-awesome-bucket"
}'

As a result, we should get 200 OK without a response body.

Upload File to S3 Bucket

Nextly, let’s take a look at how to upload a new file to S3.

We have a few options, among which the store function is the easiest:

@PostMapping("/{bucketName}/objects")
fun createObject(@PathVariable bucketName: String, @RequestBody request: ObjectRequest) {
  s3Template.store(bucketName, request.objectName, request.content)
}

data class ObjectRequest(val objectName: String, val content: String)

As we can see, this function takes three arguments:

• the bucket name,
• filename,
• and the content to upload (to be specific Object object)

Alternatively, we could use the upload function, which allows us to send InputStream instance and metadata:

@Override
public S3Resource upload(
  String bucketName, 
  String key, 
  InputStream inputStream,
  @Nullable ObjectMetadata objectMetadata
) 

Lastly, let’s verify that everything is fine with the following curl:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--header 'Content-Type: application/json' \
--data-raw '{
    "objectName": "file-example.txt",
    "content": "My file content"
}'

If everything worked, then a new file should be present in our bucket 🙂

List Files From The Bucket

Nextly, let’s see how we can list the bucket content with S3Template:

@GetMapping("/{bucketName}/objects")
fun listObjects(@PathVariable bucketName: String): List<String> =
  s3Template.listObjects(bucketName, "")
    .map { s3Resource -> s3Resource.filename }

We can clearly see that this is not rocket science 😉

Nevertheless, it is worth mentioning that this time we get the S3Resource instance and instead of the key() we use it getFilename method.

And just like previously, let’s see the endpoint in action:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--header 'Content-Type: application/json' \
--data-raw '{
    "objectName": "file-example.txt",
    "content": "My file content"
}'

# Response status: 200 OK
# Response body: 
[
    "file-example.txt"
]

Download a File

So what about fetching files from the S3 bucket?

With S3Template, it’s a piece of cake:

@GetMapping("/{bucketName}/objects/{objectName}")
fun getObject(@PathVariable bucketName: String, @PathVariable objectName: String): String =
  s3Template.download(bucketName, objectName).getContentAsString(UTF_8)

We specify the bucket name and the object name, and as a result, we get the S3Resource that exposes a bunch of methods. Among others, the getContentAsString that is pretty descriptive 😉

Similarly, let’s hit the endpoint:

curl --location --request GET 'http://localhost:8080/buckets/codersee-awesome-bucket/objects/file-example.txt'

# Response status: 200 OK
# Response body: 
"My file content"

Delete the Bucket

Last before least, let’s take a look at how we can get rid of the bucket:

@DeleteMapping("/{bucketName}")
fun deleteBucket(@PathVariable bucketName: String) {
  s3Template.listObjects(bucketName, "")
    .forEach { s3Template.deleteObject(bucketName, it.filename) }

  s3Template.deleteBucket(bucketName)
}

And just like in the previous article- we must ensure the bucket does not contain any objects.

To do so, we list out objects by specifying the bucket name and objects prefix (as we don’t have any, we pass an empty String). Then, for each object, we use its key to delete it. And lastly, we simply invoke the deleteBucket by passing the name of a bucket to delete.

Of course, let’s verify this logic, too:

curl --location --request DELETE 'http://localhost:8080/buckets/codersee-awesome-bucket'

If we run this command and the S3 bucket exists, then we should see 200 OK and our bucket will disappear.

Serialize/Deserialize objects

As the last thing, let’s take a look at how easily we can persist objects using the combination of store and read functions:

@PostMapping("/{bucketName}/objects")
fun createExampleObject(@PathVariable bucketName: String): Example {
  val example = Example(id = UUID.randomUUID(), name = "Some name")

  s3Template.store(bucketName, "example.json", example)

  return s3Template.read(bucketName, "example.json", Example::class.java)
}

data class Example(val id: UUID, val name: String)

As we can see, we made a small update to our POST /{bucketName}/objects endpoint logic.

Basically, the first part is exactly the same, we use the store again to push the file to the bucket.

Nevertheless, instead of the download we saw previously, we use the read function that uses the S3ObjectConverter that will automatically deserialize the JSON into the Example class instance.

And for the last time, let’s hit our API:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--data-raw ''

# Response status: 200 OK 
# Response body: 
{
    "id": "3eacd8a3-48b2-4756-86db-e4c9f4e291da",
    "name": "Some name"
}

And as we can see, the output confirms that everything is working fine.

Summary

And that’s all for this article on how to make our lives easier in Spring Boot with S3Template.

I hope you enjoyed it, and again wanted to invite you to take a look at other content of this series:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 (This article)
• #3 Test Spring Boot AWS S3 with Localstack and Testcontainers

Lastly, just wanted to show that you can find the source code in this GitHub repository and that you can join my newsletter to stay up-to-date with Kotlin on the backend.

The post Spring Boot with Kotlin, AWS S3, and S3Template appeared first on Codersee blog- Kotlin on the backend.

What can you expect today?

Well, at the end of this tutorial, you will know precisely how to connect to the S3 service, resolve the most common issues related to that, as well as how to perform basic operations on buckets and objects using the S3Client approach.

In the future content, we will work a bit with an asynchronous client, learn when to use S3Template instead, and learn how to write tests properly, so do not hesitate to subscribe to my newsletter 😉

Video Tutorial

If you prefer video content, then check out my video that covers all three articles:

If you find this content useful, please leave a subscription 🙂

Project Setup

If you already have your Spring Boot project prepared, then feel free to skip this step.

But if that is not the case, then let’s navigate together to the Spring Initializr page and select the following settings:

As we can see, nothing related to the AWS S3 yet, but we imported the Spring Web dependency so that we could expose REST endpoints to test.

As always, please generate the project, extract it on your local, and import it to your favorite IDE.

AWS S3 Dependencies

It is worth mentioning that the S3Client is not a Spring Boot concept, but a class that comes from the AWS SDK.

However, to make our lives easier when working with Spring, we can make use of the Spring Cloud AWS, which simplifies using AWS-managed services in a Spring and Spring Boot applications.

To do so, let’s navigate to the build.gradle.kts and add the following:

implementation("io.awspring.cloud:spring-cloud-aws-starter-s3:3.1.1")

Why do I pick it over the AWS Java SDK?

Because it auto-configures various S3 integration-related components out of the box. Additionally, we can quickly configure a bunch of things using the application.yaml. And lastly, we are all Spring boyzz here, we don’t do things manually 🙂

Create Test S3 Bucket

Following, let’s navigate to the AWS Console to prepare a test bucket.

Again, feel free to skip it if you are looking for Spring Boot details.

Then, let’s find the S3 (aka “Simple Storage Service”) in the search bar:

Nextly, let’s hit the Create Bucket , provide a name for it, and leave the rest as is:

If everything succeeded, then we should see our bucket on the list:

Excellent, at this point we can get back to our Spring Boot project :).

Test S3Client Connection

With all of that done, let’s figure out whether we can connect our local app with AWS using the S3Client.

To do so, let’s create the BucketController class and introduce the GET endpoint:

@RestController
@RequestMapping("/buckets")
class BucketController(
  private val s3Client: S3Client
) {

  @GetMapping
  fun listBuckets(): List<String> {
    val response = s3Client.listBuckets()

    return response.buckets()
      .mapIndexed { index, bucket ->
        "Bucket #${index + 1}: ${bucket.name()}"
      }
  }
}

As we can see, the above logic will be responsible for exposing the GET /buckets endpoint and returning a list of bucket names as “Bucket #N: some-name”.

Moreover, the starter we are using automatically configures and registers an S3Client bean in the Spring Boot context. So, we simply inject that without any previous configuration.

Anyway, less talkie-talkie, and let’s test the endpoint:

curl --location --request GET 'http://localhost:8080/test' 

And depending on our local environment, we get the 200 OK with a bucket name:

[
    "Bucket #1: your-awesome-name"
]

Or the error related to AwsCredentialsProviderChain:

software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(), EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(profileName=default, profileFile=ProfileFile(sections=[])), ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()]) : [SystemPropertyCredentialsProvider(): Unable to load credentials from system settings. Access key must be specified either via environment variable (AWS_ACCESS_KEY_ID) or system property (aws.accessKeyId)., EnvironmentVariableCredentialsProvider(): Unable to load credentials from system settings. Access key must be specified either via environment variable (AWS_ACCESS_KEY_ID) or system property (aws.accessKeyId)., WebIdentityTokenCredentialsProvider(): Either the environment variable AWS_WEB_IDENTITY_TOKEN_FILE or the javaproperty aws.webIdentityTokenFile must be set., ProfileCredentialsProvider(profileName=default, profileFile=ProfileFile(sections=[])): Profile file contained no credentials for profile ‘default’: ProfileFile(sections=[]), ContainerCredentialsProvider(): Cannot fetch credentials from container – neither AWS_CONTAINER_CREDENTIALS_FULL_URI or AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variables are set., InstanceProfileCredentialsProvider(): Failed to load credentials from IMDS.]

Or even:

Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [software.amazon.awssdk.services.s3.S3ClientBuilder]: Factory method ‘s3ClientBuilder’ threw exception with message: Unable to load region from any of the providers in the chain software.amazon.awssdk.regions.providers.DefaultAwsRegionProviderChain@15f35bc3: [software.amazon.awssdk.regions.providers.SystemSettingsRegionProvider@2bfb583b: Unable to load region from system settings. Region must be specified either via environment variable (AWS_REGION) or system property (aws.region)., software.amazon.awssdk.regions.providers.AwsProfileRegionProvider@7301eebe: No region provided in profile: default, software.amazon.awssdk.regions.providers.InstanceProfileRegionProvider@76a805b7: Unable to contact EC2 metadata service.]

So, let’s learn why it worked (or not🙂).

Configuring AWS Credentials

Long story short, the Spring Cloud AWS starter configures the DefaultCredentialsProvider that looks for credentials in the following order:

1. Java System Properties – aws.accessKeyId and aws.secretAccessKey
2. Environment Variables – AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
3. Web Identity Token credentials from system properties or environment variables
4. Credential profiles file at the default location (~/.aws/ credentials) shared by all AWS SDKs and the AWS CLI
5. Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
6. Instance profile credentials delivered through the Amazon EC2 metadata service

And if you got 200 OK, but you don’t remember specifying anything on your local machine, then I am pretty sure that the number 4  is the answer here 😉

The .aws folder inside the home directory is a default location for credentials, and you could have populated that unconsciously, for example when configuring AWS CLI with aws configure. And the DefaultCredentialsProvider was smart enough to use it without your knowledge.

The autoconfiguration is a wonderful thing, but as we can see, it can backfire sometimes 🙂

On the other hand, if none of these 6 satisfies you, then Spring Cloud AWS allows us to use the access keys, too.

To do so, the only thing we need to do is add the following to the application.yaml:

spring:
  cloud:
    aws:
      credentials:
        access-key: your-access-key
        secret-key: your-secret-key

Configure Region

OK, so at this point the problem related to the credentials should be gone. However, if we got the second error related to the region, then let’s see how it works internally, too.

Well, when we take a look at the DefaultAwsRegionProviderChain docs, we will see that it looks for the region in this order:

1. Check the aws.region system property for the region.
2. Check the AWS_REGION environment variable for the region.
3. Check the {user. home}/.aws/ credentials and {user. home}/.aws/config files for the region.
4. If running in EC2, check the EC2 metadata service for the region.

So, again, if we had the .aws credentials set, then this value came from there😉

And as you might already have guessed, yes, we can update that in the properties, too:

spring:
  cloud:
    aws:
      s3:
        region: us-east-1 #default is us-west-1

And at this point, when we rerun our application, then everything should be working, as expected.

AWS S3Client Operations

So, with all of that done, we can finally take a look at a few AWS S3Client capabilities. Of course, we will not cover all possible scenarios, so if you have a bit more specific use case, then I recommend checking the Spring Cloud AWS / AWS SDK documentation.

List All Buckets

Firstly, let’s get back to the listBuckets usage:

@GetMapping
fun listBuckets(): List<String> {
  val response = s3Client.listBuckets()

  return response.buckets()
    .mapIndexed { index, bucket ->
      "Bucket #${index + 1}: ${bucket.name()}"
    }
}

Long story short, this function returns ListBucketsResponse that contains a list of all buckets owned by us. It is worth mentioning that we must have the s3:ListAllMyBucket permission.

Nevertheless, I wanted to emphasize one, important thing.

AWS SDK methods throw exceptions quite heavily. For example, the above may result in SdkException, S3Exception, or SdkClientException to be thrown. In a production-ready code, we must keep that in mind, handle them according to our needs and (if necessary) translate to appropriate HTTP status codes.

Create New S3 Bucket

Following, let’s expose a POST /buckets endpoint that will be used to create new buckets:

@PostMapping
fun createBucket(@RequestBody request: BucketRequest) {
  val createBucketRequest = CreateBucketRequest.builder()
    .bucket(request.bucketName)
    .build()

  s3Client.createBucket(createBucketRequest)
}

data class BucketRequest(val bucketName: String)

This time our function looks quite different- we must prepare the CreateBucketRequest that we pass to the createBucket function.

And that is quite a common thing when dealing with AWS S3Client in Spring Boot. The SDK methods expect us to provide different objects of classes extending the S3Request, like CreateBucketRequest, DeleteObjectRequest, etc.

What the createBucket does is pretty obvious, but we must be cautious about the bucket name, because the function may throw BucketAlreadyExistsException, or BucketAlreadyOwnedByYouException.

Of course, to test that, the only thing we need to do is to hit the endpoint:

curl --location --request POST 'http://localhost:8080/buckets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bucketName": "your-awesome-name"
}'

And if everything is fine, a new bucket should be created.

Create Object In The Bucket

So at this point, we know how to create buckets in AWS. Nevertheless, we use them to organise uploaded files.

And it is the right time to learn how we can upload a file:

// we must add the typealias to avoid name clash for the @RequestBody annotation :) 
typealias PutObjectRequestBody = software.amazon.awssdk.core.sync.RequestBody

@RestController
@RequestMapping("/buckets")
class BucketController(
  private val s3Client: S3Client
) {

  @PostMapping("/{bucketName}/objects")
  fun createObject(@PathVariable bucketName: String, @RequestBody request: ObjectRequest) {
    val createObjectRequest = PutObjectRequest.builder()
      .bucket(bucketName)
      .key(request.objectName)
      .build()

    val fileContent = PutObjectRequestBody.fromString(request.content)

    s3Client.putObject(createObjectRequest, fileContent)
  }

  data class ObjectRequest(val objectName: String, val content: String)
}

As we can see, this time, we make use of the putObject and the PutObjectRequest (you see the pattern now 😉 ).

Moreover, when preparing the request we must specify both the bucket name and our object key.

curl --location --request POST 'http://localhost:8080/buckets/your-awesome-name/objects' \
--header 'Content-Type: application/json' \
--data-raw '{
    "objectName": "file-example.txt",
    "content": "My file content"
}'

As a result, a new text file named “file-example” with “My file content” in it should be created in the “your-awesome-name” bucket.

Of course, this is not the only method of S3Client that allows us to upload files, and sometimes the multipart upload might be a better choice for our use case.

List Objects From The Bucket

Nextly, let’s take a look what is the content of our bucket:

@GetMapping("/{bucketName}/objects")
fun listObjects(@PathVariable bucketName: String): List<String> {
  val listObjectsRequest = ListObjectsRequest.builder()
    .bucket(bucketName)
    .build()

  val response = s3Client.listObjects(listObjectsRequest)

  return response.contents()
    .map { s3Object -> s3Object.key() }
}

Similarly, we build the ListObjectsRequest instance, we perform the request using the listObjects and return an array with item names.

And this time, when we check with the following query:

curl --location --request GET 'http://localhost:8080/buckets/your-awesome-name/objects'

We should get the 200 OK with the array:

[
    "file-example.txt"
]

Fetch The Object From S3 Bucket

And although listing objects might be sometimes useful, I am pretty sure you would be more often interested in getting the actual object with a key:

@GetMapping("/{bucketName}/objects/{objectName}")
fun getObject(@PathVariable bucketName: String, @PathVariable objectName: String): String {
  val getObjectRequest = GetObjectRequest.builder()
    .bucket(bucketName)
    .key(objectName)
    .build()

  val response = s3Client.getObjectAsBytes(getObjectRequest)

  return response.asString(UTF_8)
}

Just like in the previous examples, we prepare the request with bucket name and object key, invoke the getObjectAsBytes and this time we print out the content to the output:

curl --location --request GET 'http://localhost:8080/buckets/your-awesome-name/objects/file-example.txt'

# Response: 
"My file content"

Of course, a friendly reminder that the AWS SDK throws the exceptions, and if the file does not exist, we will get the NoSuchKeyException.

Delete S3 Bucket

As the last step, let’s take a look at the logic necessary to delete a bucket:

@DeleteMapping("/{bucketName}")
fun deleteBucket(@PathVariable bucketName: String) {
  val listObjectsRequest = ListObjectsRequest.builder()
    .bucket(bucketName)
    .build()

  val listObjectsResponse = s3Client.listObjects(listObjectsRequest)

  val allObjectsIdentifiers = listObjectsResponse.contents()
    .map { s3Object ->
      ObjectIdentifier.builder()
        .key(s3Object.key())
        .build()
    }

  val del = Delete.builder()
    .objects(allObjectsIdentifiers)
    .build()

  val deleteObjectsRequest = DeleteObjectsRequest.builder()
    .bucket(bucketName)
    .delete(del)
    .build()

  s3Client.deleteObjects(deleteObjectsRequest)


  val deleteBucketRequest = DeleteBucketRequest.builder()
    .bucket(bucketName)
    .build()

  s3Client.deleteBucket(deleteBucketRequest)
}

As we can see, this time, we must perform our actions in a few steps.

Why?

The reason is simple:

Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: software.amazon.awssdk.services.s3.model.S3Exception: The bucket you tried to delete is not empty (Service: S3, Status Code: 409…

As we can see, the message above is pretty descriptive. Simply said- we cannot delete a bucket that is not empty.

So, our function utilizes the listObjects, so that we can get keys to delete, the deleteObjects to actually delete them, and deleteBucket to get rid of the bucket.

Summary

And that’s all for this first tutorial on how to integrate your Spring Boot application with AWS and make use of the S3Client to work with AWS S3. In the upcoming articles in the series, we will expand our knowledge to work with S3 even more efficiently.

Of course, I highly encourage you to take a look at the remaining articles in this series:

• #3 Test Spring Boot AWS S3 with Localstack and Testcontainers

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

The post Spring Boot with AWS S3, S3Client and Kotlin appeared first on Codersee blog- Kotlin on the backend.

Moreover, we will take a quick look into the Spring Boot Actuator and how it can help us, so, to let’s not waste our time and let’s get to work! 🙂

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription 🙂

Datadog

If you came here directly, then I bet you already know what Datadog is and what purpose it will serve in your project.

However, for those who hear about it for the first time, let me give you a really short intro.

Long story short- Datadog is an integrated platform for monitoring & security. It provides tools for monitoring applications, databases, distributed tracing, logs management, and many many more. In other words, makes all the things that are not so cool, but necessary in production-ready environments, a bit less painful 😉

However, what is the most important for us today- it provides tools to collect metrics from our applications so that later we can make use of them.

But, what are they?

What Are Metrics?

According to the Datadog documentation:

Metrics are numerical values that can track anything about your environment over time.

And I must admit- I love this definition for its completeness in its simplicity.

Because basically, metric is everything in our system that we can assign a number to and track. From Garbage Collector stats, JVM memory, CPU, and request latency, to the average cart size. Literally everything.

And in this tutorial, we will see how to send metrics collected automatically by our Spring Boot app to DataDog.

Create New Project

As the first step, let’s navigate to the Spring Initializr page, select the following and import the project to our IDE:

Apart from versions and metadata, we can see that we added two dependencies: Spring Web and Spring Boot Actuator.

The first one is quite obvious, but in terms of metrics Spring Boot Actuator provides dependency management and auto-configuration for Micrometer – a vendor-neutral application observability facade.

With that, Spring Boot takes care of configuring MeterRegistry and the only thing we need to do is to add the micrometer-registry-{system} dependency to the build.gradle.kts :

implementation("io.micrometer:micrometer-registry-datadog")

Note: we could achieve exactly the same using the Spring Initializr page and searching for the Datadog dependency, but I wanted to emphasize the fact, that other vendors, like Elastic, or OpenTelemetry can be added in the same manner.

Verify and Expose Metrics Endpoint

After we import our project, let’s run it, and let’s take a look at the endpoints exposed by default by Spring Boot Actuator:

curl --location --request GET 'http://localhost:8080/actuator' 

As a result, we should see the following:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        }
    }
}

And the first lesson is that the metrics endpoint is not exposed by default.

So to change that, let’s navigate to the application.yaml and add the following:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health

After that, let’s rerun the application.

As a result, this time, we should see that two new endpoints are present:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        },
        "metrics-requiredMetricName": {
            "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
            "templated": true
        },
        "metrics": {
            "href": "http://localhost:8080/actuator/metrics",
            "templated": false
        }
    }
}

The last one- /actuator/metrics– simply displays a list of available meter names, and when we invoke it, we should see the following JSON response:

{
    "names": [
        "application.ready.time",
        "application.started.time",
        "disk.free",
        "disk.total",
        "executor.active",
        "executor.completed",
        "executor.pool.core",
        "executor.pool.max",
        "executor.pool.size",
        "executor.queue.remaining",
        "executor.queued",
        "http.server.requests",
        "http.server.requests.active",
        "jvm.buffer.count",
        "jvm.buffer.memory.used",
        "jvm.buffer.total.capacity",
        "jvm.classes.loaded",
        "jvm.classes.unloaded",
        "jvm.compilation.time",
        "jvm.gc.concurrent.phase.time",
        "jvm.gc.live.data.size",
        "jvm.gc.max.data.size",
        "jvm.gc.memory.allocated",
        "jvm.gc.memory.promoted",
        "jvm.gc.overhead",
        "jvm.gc.pause",
        "jvm.info",
        "jvm.memory.committed",
        "jvm.memory.max",
        "jvm.memory.usage.after.gc",
        "jvm.memory.used",
        "jvm.threads.daemon",
        "jvm.threads.live",
        "jvm.threads.peak",
        "jvm.threads.started",
        "jvm.threads.states",
        "logback.events",
        "process.cpu.time",
        "process.cpu.usage",
        "process.start.time",
        "process.uptime",
        "system.cpu.count",
        "system.cpu.usage",
        "tomcat.sessions.active.current",
        "tomcat.sessions.active.max",
        "tomcat.sessions.alive.max",
        "tomcat.sessions.created",
        "tomcat.sessions.expired",
        "tomcat.sessions.rejected"
    ]
}

In simple words, this is the list of all metrics collected at this point by our Spring Boot application. And yes- we will be able to export them to Datadog.

Nevertheless, let’s verify what the second endpoint- /actuator/metrics/{requiredMetricName}– does.

To do that, let’s make a GET request and specify any metric name:

curl --location --request GET 'http://localhost:8080/actuator/metrics/process.cpu.usage'

This time, the endpoint will return metric details along with the current value:

{
    "name": "process.cpu.usage",
    "description": "The \"recent cpu usage\" for the Java Virtual Machine process",
    "measurements": [
        {
            "statistic": "VALUE",
            "value": 0.038209510879134205
        }
    ],
    "availableTags": []
}

Create Datadog Account

Excellent! At this point, we are sure that our Spring Boot app collects metrics, so it’s time to proceed with the Datadog part.

If you haven’t done it yet, then let’s create a trial account together.

Let’s navigate to the https://www.datadoghq.com/ and click the “Free trial” button:

Following, let’s fill out the signup form:

And with that done, when we confirm our e-mail address, we will land on this page:

As we can see, the above page contains a bunch of guides on how to set up the agent.

And although we are not interested in any of those, this page has one, valuable information for us- the API key.

Note: I think that readers of this blog are well aware of that, but for my own peace of mind- API keys are vulnerable data, so you must be cautious with them! 🙂

At this point, please copy this value and we will use it in the proceeding steps.

Configure App To Send Metrics

When we have our Datadog account ready, we can finally configure our app.

API Key

Firstly, let’s get back to our Spring Boot project and update the application.yaml :

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE

Of course, we must replace the YOUR_KEY_VALUE with the actual API key.

Update Datadog URI

If you are using Datadog US (the option you could select when signing up), then that’s pretty much it and you can restart the application.

By default, metrics are sent to the Datadog US site (api.datadoghq.com). If your Datadog project is hosted on one of the other sites, or you need to send metrics through a proxy, configure the URI accordingly.

So given the above, if we use another region, then we need to add one more line:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu

Update Metrics Upload Interval

Following, let’s see how easily we can update the interval, in which data are sent to Datadog:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu
        step: 10s

The default value is 30 seconds. And to change that, the only thing we need to do is to add the step value.

Set Spring Logging Level to DEBUG

As the last thing, which technically is not directly related to sending metrics, I would like to add the following to the root of our application.yaml file:

logging:
  level:
    root: DEBUG

This way we set the logging level in our Spring Boot application to DEBUG.

Why? It will be useful in a moment when we will be testing our implementation.

Testing

With all of that done, we can finally verify that everything is working properly.

Verify Spring Boot Sends Data to Datadog

Firstly, let’s rerun our application and take a look at the logs.

If we see the following:

i.m.datadog.DatadogMeterRegistry         : successfully sent 78 metrics to datadog

Then data are successfully sent to the Datadog API.

Let’s leave it running for some time (like 2 minutes, or something), so that we have actual data later to work with 🙂

Review Metrics in Datadog

After that time, the only thing left is to take a look at metrics in Datadog.

If we haven’t closed the Datadog “Agent Setup” page, then it should automatically close and redirect us to the dashboard.

However, if that didn’t happen, then no worries, we can simply navigate to the metrics summary page:

On this page, we can see all the metrics that have been gathered so far. Long story short, this page contains meta-information about metrics themselves, like tags, etc.

I strongly recommend you spend here some time and figure out different options.

And if we would like to take a look at the actual values, then let’s navigate to the metrics explorer:

I know, the image is quite small (the “Open Image in New Tab” option will help here 😉 ). However, the only thing we need to do here is to specify the metric name in the left upper part and the period we would like to view in the right upper part.

After that, we will see the above chart.

And basically, that’s how metrics work with Spring Boot and Datadog, but please don’t close this article yet, I wanted to show you two, interesting things that may be useful to you in real life.

Sending Custom Tags

Tags are nothing else, than additional metadata you can send with metrics.

Why are they useful? Well, thanks to them we can later differentiate different metrics. For example, we can send a tag with the application name, so that later we will group metrics by microservices, or environment value, like dev, staging, or prod.

In Spring Boot, we have several ways to achieve that. And probably the easiest way is to (again) update the application.yaml:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu
        step: 10s
  metrics:
    tags:
      application: "my-app-one"

As we can see, we can add a custom tag by using metrics.tags and specifying that as a key-value pair. In our case- the application tag has the my-app-one value.

This approach is not only straightforward but also quite flexible. We could always put a placeholder for the environment variable instead of the hardcoded value.

Anyway, when we rerun our application and let Spring send some metrics to the Datadog, we will see that from now on we can filter values using the “from” field:

Again, the “Open Image in New Tab” may be helpful here 😉

Turn Off Metrics Export

As the last thing, let’s take a look at how we can instruct our Spring app to stop sending metrics to Datadog.

Again, let’s navigate to the application.yaml file and set the enabled flag to false:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        enabled: false
        api-key: YOURE_KEY_VALUE
        uri: https://api.datadoghq.eu
        step: 10s

Of course, we can use an environment variable placeholder (like ${DATADOG_ENABLED}) and turn on/off export in different environments.

Summary

That’s all for this tutorial on how to send Spring Boot metrics to Datadog.

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

Have a great day and don’t forget to leave a comment! 😀

The post Sending Spring Boot Metrics to Datadog appeared first on Codersee blog- Kotlin on the backend.

As an example, we will implement a simple logic responsible for querying the GitHub API using coroutines. Nevertheless, I am pretty sure you will be able to easily adjust this article to your needs. (of course, if you are here only for the WireMock part, then I recommend skipping to the “WebClient Integration Testing With WireMock” chapter).

Lastly, I just wanted to add that you can use this testing approach regardless of whether you are using WebClient, Retrofit, Ktor Client, or any other HTTP client.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription 🙂

Which WebClient Testing Strategy Is The Best?

But before we head to the practice part, let’s try to answer the above question.

Quick answer- there is no such thing as the best testing strategy.

And for the longer answer, let’s take a look at the visualization of the testing pyramid first:

The tests are ordered based on their scope and execution time. The closer we are to the top, the longer the tests take, but they also give us more confidence.

• unit tests form the base, as they are quick to run and pinpoint specific code issues,
• integration tests come next, validating the interactions between units,
• E2E tests, with a broader scope, are placed at the top.

So long story short, although the e2e tests give us the most confidence, we cannot rely only on them, because the feedback loop would take way too long. And this would affect the development process.

So usually, we make concessions and introduce more integration and unit tests.

But which of these two should we pick for the WebClient?

In my opinion- integration tests.

Whenever we are talking about logic responsible for communicating with external API, we must make sure that:

• we query the appropriate URL,
• we pass the necessary headers with appropriate values,
• request/response bodies are properly serialized/deserialized,
• and many, many more.

With unit testing, the amount of mocking here would be so significant that I would question whether we need such a test at all.

Moreover, in Spring we can write integration tests for WebClient with WireMock at almost no effort.

Set Up GitHub API Key

With that said, let’s set up the API key we will use to query the GitHub API.

Note: technically, the endpoint we will use does not require any token. However, for the learning purposes I want to show you how to deal with passing bearer tokens, too 🙂

As the first step, let’s navigate to the tokens tab in GitHub settings and click the “Generate new token (classic)”:

On the next page, let’s specify the name, expiration, and desired scopes:

If you don’t know what scopes you will need, please follow the principle of lowest privilege. At the end of the day, we can generate a new token at some point in the future when the requirements change.

When we are ready, let’s hit the generate button copy the token value, and store it securely. We will not see it again!

Query The Api With WebClient

Before we implement the WireMock tests, let’s prepare a simple project responsible for querying the external API with WebClient. So, even if you are here only for the WireMock part, I encourage you to briefly check this paragraph to be on the same page 😉

Long story short, we will implement WebClient with coroutines that will query the “List repositories for a user” endpoint. For more details about it, check out the GitHub API documentation, please.

Generate New Project

As the first step, let’s navigate to the https://start.spring.io/ page and generate a fresh Spring Boot project:

In general, the most important thing is that we will use Kotlin and Spring Reactive Web this time. Versions and metadata are totally up to you.

Of course, let’s click the “Generate” button, download the ZIP file, and import that to our IDE. Personally, I am using IntelliJ IDEA and if you would like to learn more about its setup, then check out my video on how to install IntelliJ for Kotlin development.

Update Application Properties

As the next step, let’s navigate to the resources package and update the application.yaml file:

api:
  github:
    key: ${GITHUB_API_TOKEN:123}
    url: ${GITHUB_API_BASE_URL:http://localhost:8090}
    version: ${GITHUB_API_VERSION:2022-11-28}

Above we can see our custom properties.

We will source values for our GitHub key, URL, and version from environment variables.

Not only is this approach secure (hardcoding the key with token value would be the worst thing you could do), but also flexible (we can pass different values depending on the environment we are running our app in).

WebClient Configuration

Following, let’s configure a WebClient bean that we will use whenever we want to call the GitHub API.

Firstly, let’s add the config package and put the GitHubApiProperties data class in there:

@ConfigurationProperties("api.github")
data class GitHubApiProperties(
    val url: String,
    val key: String,
    val version: String,
)

In my opinion, the @ConfigurationProperties annotation is the cleanest way to inject values from properties. As we can see above, the prefix and field names simply reflect the structure from the previous step.

With that done, let’s add the GitHubApiConfig in the same package:

@Configuration
@EnableConfigurationProperties(GitHubApiProperties::class)
class GitHubApiConfig(
    private val gitHubApiProperties: GitHubApiProperties,
) {
    @Bean
    fun webClient(builder: WebClient.Builder): WebClient =
        builder
            .baseUrl(gitHubApiProperties.url)
            .defaultHeader("Authorization", "Bearer ${gitHubApiProperties.key}")
            .defaultHeader("X-GitHub-Api-Version", gitHubApiProperties.version)
            .defaultHeader("Accept", "application/vnd.github+json")
            .build()
}

Quite a few things are happening here, so let’s dive into each one.

Firstly, we annotate the class with @Configuration and @EnableConfigurationproperties. The second annotation is necessary to for the previous steps to work.

Then, we inject the GitHubApiProperties instance and use its values to configure a new WebClient bean. This configuration is quite straightforward. We set the base URL and a bunch of headers that will be sent with every request: the authorization token, GH API version, and the accept header (those two are specific to the GitHub API, so let’s focus on that too much).

Prepare Model Classes

With that done, let’s prepare a bunch of data classes that we will need to deserialize JSON responses from the API (+ one exception class). If you would like to add other fields, please check out the documentation link I shared with you before.

As the first step, let’s add the model package and the PageableGitHubResponse:

data class PageableGitHubResponse<T>(
    val items: List<T>,
    val hasMoreItems: Boolean,
)

The API endpoints allow us to get only a chunk of data using the page and per_page parameters. And this class can be reused whenever we’re using a paginated endpoint.

As the next step, let’s implement the GitHubRepoResponse along with GitHubOwnerResponse:

data class GitHubRepoResponse(
    val fork: Boolean,
    val name: String,
    val owner: GitHubOwnerResponse,
)

data class GitHubOwnerResponse(
    val login: String,
)

As I mentioned at the beginning of this paragraph, we need those two in order to deserialize the actual JSON response payload.

Lastly, let’s add the UpstreamApiException:

import org.springframework.http.HttpStatusCode

data class UpstreamApiException(
    val msg: String,
    val statusCode: HttpStatusCode,
) : RuntimeException(msg)

This way, we will be able to throw custom exceptions. Such an exception could be handled later, for example with @RestControllerAdvice.

Make Use Of WebClient

Finally, let’s combine all of that together.

So, let’s add the api package and implement the GitHubApi class:

@Component
class GitHubApi(
  private val webClient: WebClient,
) {

  suspend fun listRepositoriesByUsername(
    username: String,
    page: Int,
    perPage: Int,
  ): PageableGitHubResponse<GitHubRepoResponse>? =
    webClient.get()
      .uri("/users/$username/repos?page=$page&per_page=$perPage")
      .awaitExchangeOrNull(::mapToPageableResponse)
}

Don’t worry about the mapToPageableResponse, we will add it in a moment.

But before that, let’s analyze the above code.

Firstly, we annotate the class as the @Component to make it a Spring bean and inject the WebClient instance we configured earlier. We don’t have other WebClient instances, so there is no need to use @Qualifier or anything like that.

Following, we add the listRepositoriesByUsername function that lets us pass the username along with page and perPage. This way, we make this function reusable and allow the invoker to decide how to tackle the pagination.

Additionally, we mark it as a suspend function because the awaitExchangeOrNull is a suspend function. However, if you are interested in this topic, then I refer you to my other article about WebClient with coroutines.

Lastly, let’s add the missing code:

private suspend inline fun <reified T> mapToPageableResponse(clientResponse: ClientResponse): PageableGitHubResponse<T>? {
  val hasNext = checkIfMorePagesToFetch(clientResponse)

  return when (val statusCode = clientResponse.statusCode()) {
    HttpStatus.OK ->
      PageableGitHubResponse(
        items = clientResponse.awaitBody<List<T>>(),
        hasMoreItems = hasNext,
      )

    HttpStatus.NOT_FOUND -> null

    else -> throw UpstreamApiException(
      msg = "GitHub API request failed.",
      statusCode = statusCode,
    )
  }
}

fun checkIfMorePagesToFetch(clientResponse: ClientResponse) =
  clientResponse.headers()
    .header("link")
    .firstOrNull()
    ?.contains("next")
    ?: false

Long story short, the above code works as follows:

1. Firstly, we take the response and check if there are more pages. How? Well, without going into details, GitHub API returns the link header. And if its value contains the rel="next", it means that there are more pages to fetch.
2. Finally, we check the status code. If it is 200 OK, we simply read the JSON value. When we get 404 Not Found, we return null (we can expect this status code when we pass a non-existing username, and in my opinion, this case is not exceptional). And whenever we receive another status code, we simply throw the UpstreamApiException.

WebClient Integration Testing With WireMock

Excellent, at this point we have (almost) everything we need to test our WebClient implementation with WireMock.

We will see only a few example test cases that you will be able to easily adapt according to your needs:

• 200 OK response with an empty list, 200 OK with items, and more pages, and 200 OK with items and no more pages to fetch
• 404 Not Found,
• 401 Unauthorized

When you will be implementing your own integration tests, this is the moment when you should do the homework and analyze the API you are working with. What are the possible happy paths? How should your code behave in case of any error status code? What if we add some latency? And many, many more 🙂

Additional Dependencies

At this point, we defined our test cases, so we are ready to get our hands dirty.

So, let’s start by adding the necessary dependencies:

testImplementation("org.springframework.cloud:spring-cloud-contract-wiremock:4.1.1")
testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")

As we can see, the first one- the Spring Cloud Contract WireMock module- allows us to use WireMock in our app, whereas the kotlinx-coroutines-test is necessary due to our coroutines WebClient implementation.

Add Expected JSON Files

So, if we know what test cases we would like to test, we should prepare the example JSON API responses.

Personally, whenever working with WireMock I am a big fan of externalizing the expected JSON files. We put them inside the /test/resources directory and refer to them later in the tests. This way, we can improve the readability of the test classes. Of course, unless we want to prepare JSON responses dynamically.

In our case, we could simply invoke the GitHub API and persist responses for different cases. This way, we prepare the following files and put them inside the /test/resources/responses/external/github:

• list_github_repositories_200_OK_empty_list.json
• list_github_repositories_200_OK_page_1.json
• list_github_repositories_401_UNAUTHORIZED.json
• list_github_repositories_404_NOT_FOUND.json

You can find all of these files in my GH repo here.

The example for 401 Unauthorized looks as follows:

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

Prepare Util Function

As the last thing before we implement our test class, let’s add the util function inside the util package (of course, in tests).

This function will be responsible for reading JSON files inside the test resources as String values:

import org.springframework.core.io.ClassPathResource

fun getResponseBodyAsString(path: String): String =
    ClassPathResource(path).getContentAsString(
        Charsets.UTF_8,
    )

Implement GitHubApiTest Class

Finally, let’s start implementing the GitHubApiTest class:

private const val TEST_KEY = "TEST_KEY"
private const val TEST_PORT = 8082
private const val TEST_VERSION = "2022-11-28"

@AutoConfigureWireMock(port = TEST_PORT)
@TestPropertySource(
  properties = [
    "api.github.url=http://localhost:${TEST_PORT}",
    "api.github.key=$TEST_KEY",
    "api.github.version=$TEST_VERSION",
  ],
)
@SpringBootTest(
  webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
)
class GitHubApiTest {
  @Autowired
  private lateinit var wireMockServer: WireMockServer

  @Autowired
  private lateinit var gitHubApi: GitHubApi

  private val page = 1
  private val perPage = 2
  private val username = UUID.randomUUID().toString()

}

Conceptually, everything starts with the @SpringBootTest and @AutoConfigureWireMock annotations.

We use the @SpringBootTest annotation in Spring Boot integration tests. This way a new ApplicationContext will be created. In our case, we set the webEnvironment with RANDOM_PORT value, so that a reactive context listening on the random port is created.

Additionally, we combine that together with @AutoConfigureWireMock and fixed test port. This way a WireMock server will be started as a part of Application Context.

Lastly, we do 3 things:

1. We use the @TestPropertySource to pass values for properties.
2. We inject the WireMockServer and GitHubApi instances that we will work with later. Please note that we can do that just like we would do with a standard, non-test, Spring component.
3. We prepare some dummy data for page, perPage, and username values we will need for testing.

As a note of comment from my side- this “skeleton” is useful whenever working with WebClient and WireMock.

Test 404 Not Found API Response Case

Wonderful!

As the first test, let’s start with the 404 Not Found case. Usually, we will start with happy path cases, but for learning purposes, this one is the shortest case 😉

@Test
fun `Given 404 NOT FOUND response When fetching repository by username Then should return null`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.NOT_FOUND.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_404_NOT_FOUND.json"),
          ),
      ),
  )

  // When
  val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

  // Then
  Assertions.assertNull(result)
}

We mark our test with the @Test (JUnit 5), specify the meaningful name for the test (with awesome Kotlin backticks), and wrap our test with runTest. The last one is necessary as we are working with coroutines and invoke the suspended function. Long story short, in JVM it will behave just like runBlocking (but it will skip delays).

Next comes the WireMock part. And to be even more specific- stubbing.

Stubbing is nothing else than “the ability to return canned HTTP responses for requests matching criteria” (from docs). Simply said, whenever an outgoing request that matches our criteria is made, a mocked response configured in willReturn is returned.

So, as we can see, the above logic will work only when:

• the GET request is made,
• URL matches,
• Headers sent have appropriate values

And this part already tests our logic. Pretty neat, isn’t it? 🙂

Lastly, we simply invoke the function and assert that null is returned. Which confirms that everything is working fine.

Test 401 Unauthorized

As we already started with error cases, let’s verify that whenever the endpoint returns 401 Unauthorized, the UpstreamApiException is thrown:

@Test
fun `Given 401 UAUTHORIZED response When fetching repository by username Then should throw UpstreamApiException`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.UNAUTHORIZED.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_401_UNAUTHORIZED.json"),
          ),
      ),
  )

  // When
  val exception = assertThrows<UpstreamApiException> {
    gitHubApi.listRepositoriesByUsername(username, page, perPage)
  }

  // Then
  assertNotNull(exception)

  assertEquals("GitHub API request failed.", exception.msg)
  assertEquals(HttpStatus.UNAUTHORIZED, exception.statusCode)
}

As we can see, the logic responsible for stubbing only slightly changed.

The interesting part here is the assertThrows, which not only makes sure that the exception of an appropriate type is thrown but also returns it. This way we can make additional assertions.

Verify 200 OK With Empty List

Following, let’s cover the empty list case:

@Test
fun `Given 200 OK response with empty list When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_empty_list.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items = emptyList<GitHubRepoResponse>(),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

This time, we assign the returned value to the result and compare that with the expected.

Check 200 OK With Has Next True

Last before least, let’s make sure that we got the expected objects in a list and that the logic responsible for the link header check returns true:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next true`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="next","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = true,
      )

    assertEquals(expected, result)
  }

Test 200 OK With Has Next False

And finally, let’s double-check the flag logic:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

Integration Tests With WireMock And WebClient Summary

And basically, that’s all for this tutorial on how to perform integration testing for Spring WebClient that invokes external REST APIs with WireMock and JUnit 5.

I hope you enjoyed this one and I recommend you check out my other articles related to Spring Framework.

The post Integration Tests for WebClient with WireMock appeared first on Codersee blog- Kotlin on the backend.

In this, comprehensive guide I will show you step-by-step how to:

• authenticate and authorize users,
• assign and verify roles,
• generate JWT tokens,
• and implement a refresh token flow.

And everything that with our beloved Kotlin programming language!

Video Tutorial

If you prefer video content, then you can find this tutorial as a YouTube playlist right here.

Alternatively, you can start from the introduction:

If you find this content useful, please leave a subscription  😉

What Exactly Will We Implement?

Well, in our project we will implement a REST API for articles and users.

Articles will be visible to any user who successfully authenticates using the JWT access token.

Users endpoint, on the other hand, will be accessible only for admin users in our system (with one exception- a public endpoint for creating new users).

Of course, we will expose additional authentication endpoints, which will take data from users, like email and password and generate access and refresh tokens for our system.

Long story short- I believe this project will be simple enough to easily understand the topic, and comprehensive enough to cover the most popular real-life cases.

A Tiny Bit Of Theory

In this paragraph, I’d like to cover what exactly JWT tokens are, the difference between authorization and authentication, and present from a bird’s eye view how Spring Security works.

So, if you feel that you understand these and came here for the practice, then please skip to the next chapter 😉

Authentication vs Authorization

I am pretty sure that you heard both terms plenty of times already and even heard people using them alternately.

Nevertheless, although similar, these two terms refer to completely different things.

Imagine you’re at the entrance of a super-secret club:

Authentication is like showing your ID to prove you are who you say you are. It’s the process of confirming your identity. So, in our club scenario, it’s like showing your driver’s license to the bouncer.

Authorization, on the other hand, is like being allowed into different parts of the club based on your VIP status. Once you’re inside (thanks to authentication), authorization decides what you can and cannot do. For example, VIP members might access the VIP lounge, while regular guests can’t.

JWT Tokens

Among plenty of existing ways to authenticate users, JWTs (JSON Web Tokens) are one of the most popular ones.

They are like a digital secret handshake on the internet. When we log into a website, the server gives us a special JWT. This token is like a digital badge that says, “Hey, this person is legit!”

Why are they so cool? Well, they are safe, compact, and allow us to hold information.

JWTs consist of three parts separated by dots: header.payload.signature:

As we can see, the encoded value can be easily decoded and JWT token values can be read.

The header typically consists of two parts: the type of the token (missing above), and the signing algorithm being used (HMAC SHA512).

The second part of the token is the payload, which contains the claims. Claims, Claims are statements about an entity (typically, the user) and additional data.

Lastly, the signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

Bird’s Eye View on Spring Security

At this point, we know the difference between authentication and authorization and also what JWT tokens are. Awesome!

So, now I’ll try to do the impossible- explain how Spring Security works in a few sentences 🙂

Spring Security is like the security team of a building. It manages authentication and authorization for our app with:

1. Filters– think of security filters as checkpoints at different doors in the building. When a request comes in, it goes through these filters. These filters handle tasks like authentication and authorization. For instance, there might be a filter that checks if you have a proper access card (authentication), and another that ensures you can enter specific rooms (authorization).
2. Authentication– when you log in, Spring Security checks your credentials (like username and password). If they match, you’re authenticated. Spring Security uses authentication providers, which can be a database, LDAP, or any other source, to verify your identity.
3. Security Context– once authenticated, your security details are stored in the Security Context. It’s like being given a special pass after passing through the checkpoint. This pass (security context) contains your roles and permissions.
4. Authorization– now, when you try to access a specific part of the application, Spring Security checks your roles and permissions stored in the security context. If you’re authorized (based on your roles), you’re allowed in. Otherwise, you might be denied access.
5. Customization– Spring Security allows you to customize the security filters, authentication providers, and access rules according to your application’s requirements. You can configure which URLs need authentication, what roles are required, etc.

And that’s basically what we’re gonna learn today.

Import Spring Boot 3 Project

As the first step, let’s generate a new Spring Boot 3 project.

To do so, we can use the Spring Initializr page:

As we can see, in this project, we will use Spring Boot 3.1.5, Kotlin as a programming language, and Kotlin DSL for our Gradle build config.

At this point, the only dependency required to expose a REST API is Spring Web. We will add Spring Security, and libraries necessary for JWT tokens later (and we will see why later, too).

With all of that done, we can hit the generate button, download the zip file, and import it to IntelliJ.

Expose Articles API

Following, let’s implement the logic necessary to expose our first endpoint- GET /api/article .

In the future, this endpoint will be accessible only to users with a valid JWT token.

Create Article Model

As the first step, let’s introduce a new package- model – and create a new data class- Article:

import java.util.*

data class Article(
  val id: UUID,
  val title: String,
  val content: String,
)

This class consists of three example fields simulating a real-life article.

Implement Article Repository

Secondly, we must introduce a new class responsible for article retrieval and storage.

Let’s add the repository package and implement ArticleRepository:

import com.codersee.jwtauth.model.Article
import org.springframework.stereotype.Repository
import java.util.UUID

@Repository
class ArticleRepository {

  private val articles = listOf(
    Article(id = UUID.randomUUID(), title= "Article 1", content= "Content 1"),
    Article(id = UUID.randomUUID(), title= "Article 2", content= "Content 2"),
  )

  fun findAll(): List<Article> =
    articles

}

In our example, articles are nothing else, than a hardcoded private list of items.

Additionally, we expose the findAll() method, which encapsulates the list and which we will be invoking from outside the class.

Of course, I did it this way to keep it simple and so that we do not lose focus on what matters in this tutorial- Spring Boot security with Kotlin and JWT tokens.

Nevertheless, you can easily adjust this project to your needs. In real life, this would be the class where you can put logic responsible for communication with your database.

Create Service

As the next step, let’s create the service package and introduce the ArticleService:

import com.codersee.jwtauth.model.Article
import com.codersee.jwtauth.repository.ArticleRepository
import org.springframework.stereotype.Service

@Service
class ArticleService(
  private val articleRepository: ArticleRepository
) {

  fun findAll(): List<Article> =
    articleRepository.findAll()
}

As we can see, this class exposes the findAll() function and does nothing else than invoking the findAll() method from our repository.

Again, this might look a bit like an overengineering. But trust me, keeping a well-organized project from the very beginning will pay off in the future.

Expose Article REST API

Lastly, let’s add the controller.article package and put two classes in it.

Let’s start with the ArticleResponse:

import java.util.*

data class ArticleResponse(
  val id: UUID,
  val title: String,
  val content: String,
)

Before returning any article from our REST API, we will map model objects into the response objects.

And with that done, let’s implement the ArticleController:

import com.codersee.jwtauth.model.Article
import com.codersee.jwtauth.service.ArticleService
import org.springframework.web.bind.annotation.*
import java.util.*

@RestController
@RequestMapping("/api/article")
class ArticleController(
  private val articleService: ArticleService
) {

  @GetMapping
  fun listAll(): List<ArticleResponse> =
    articleService.findAll()
      .map { it.toResponse() }

  private fun Article.toResponse(): ArticleResponse =
    ArticleResponse(
      id = this.id,
      title = this.title,
      content = this.content,
    )
}

As we can see, we must annotate our controller class with the @RestController annotation in order to expose a REST API in Spring Boot.

Additionally, we add the @RequestMapping annotation so that whenever we hit the /api/article endpoint, Spring knows that this is the class it should use to handle the request.

Lastly, we mark the listAll() function with @GetMapping, and convert all found Article instances to the ArticleResponse.

Later, when we add the JWT security to our Spring Boot Kotlin project, these endpoints will be accessible only for ADMIN users with one exception- the endpoint responsible for creating new users- which will be publicly exposed.

Add User Model

With that said, let’s add the User.kt file to the model package:

import java.util.*

data class User(
  val id: UUID,
  val email: String,
  val password: String,
  val role: Role
)

enum class Role {
  USER, ADMIN
}

As we can see, apart from the id, the User class contains three important fields: email, password, and role, which we will extensively when dealing with JWT tokens.

Implement UserRepository

Following, let’s create the UserRepository in the repository package:

import com.codersee.jwtauth.model.Role
import com.codersee.jwtauth.model.User
import org.springframework.stereotype.Repository
import java.util.*

@Repository
class UserRepository {

  private val users = mutableSetOf(
    User(
      id = UUID.randomUUID(),
      email = "email-1@gmail.com",
      password = "pass1",
      role = Role.USER,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-2@gmail.com",
      password = "pass2",
      role = Role.ADMIN,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-3@gmail.com",
      password = "pass3",
      role = Role.USER,
    ),
  )

  fun save(user: User): Boolean =
    users.add(user)

  fun findByEmail(email: String): User? =
    users
      .firstOrNull { it.email == email }

  fun findAll(): Set<User> =
    users

  fun findByUUID(uuid: UUID): User? =
    users
      .firstOrNull { it.id == uuid }

  fun deleteByUUID(uuid: UUID): Boolean {
    val foundUser = findByUUID(uuid)

    return foundUser?.let {
      users.removeIf {
        it.id == uuid
      }
    } ?: false
  }
}

Similarly to our previous repository- we simply introduce a mutable list, which we can edit with a bunch of util methods.

And don’t worry about the password stored in plain text- we will get back to that topic, too 🙂

Add UserService

Nextly, we must go to the service package and introduce this UserService:

import com.codersee.jwtauth.model.User
import com.codersee.jwtauth.repository.UserRepository
import org.springframework.stereotype.Service
import java.util.*

@Service
class UserService(
  private val userRepository: UserRepository
) {

  fun createUser(user: User): User? {
    val found = userRepository.findByEmail(user.email)

    return if (found == null) {
      userRepository.save(user)
      user
    } else null
  }

  fun findByUUID(uuid: UUID): User? =
    userRepository.findByUUID(uuid)

  fun findAll(): List<User> =
    userRepository.findAll()
      .toList()

  fun deleteByUUID(uuid: UUID): Boolean =
    userRepository.deleteByUUID(uuid)
}

Nothing spectacular here, so let’s move to the next step.

Expose User REST API

Just like with articles, let’s start with introducing request/response objects.

This time, we will need both the UserRequest:

data class UserRequest(
  val email: String,
  val password: String,
)

And the UserResponse, which will be serialized into JSON objects:

import java.util.*

data class UserResponse(
  val uuid: UUID,
  val email: String,
)

And with that done, we can add the UserController class:

import com.codersee.jwtauth.model.Role
import com.codersee.jwtauth.model.User
import com.codersee.jwtauth.service.UserService
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*
import org.springframework.web.server.ResponseStatusException
import java.util.*

@RestController
@RequestMapping("/api/user")
class UserController(
  private val userService: UserService
) {

  @PostMapping
  fun create(@RequestBody userRequest: UserRequest): UserResponse =
    userService.createUser(userRequest.toModel())
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.BAD_REQUEST, "Cannot create user.")

  @GetMapping
  fun listAll(): List<UserResponse> =
    userService.findAll()
      .map { it.toResponse() }

  @GetMapping("/{uuid}")
  fun findByUUID(@PathVariable uuid: UUID): UserResponse =
    userService.findByUUID(uuid)
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User not found.")


  @DeleteMapping("/{uuid}")
  fun deleteByUUID(@PathVariable uuid: UUID): ResponseEntity<Boolean> {
    val success = userService.deleteByUUID(uuid)

    return if (success)
      ResponseEntity.noContent()
        .build()
    else
      throw ResponseStatusException(HttpStatus.NOT_FOUND, "User not found.")
  }

  private fun User.toResponse(): UserResponse =
    UserResponse(
      uuid = this.id,
      email = this.email,
    )

  private fun UserRequest.toModel(): User =
    User(
      id = UUID.randomUUID(),
      email = this.email,
      password = this.password,
      role = Role.USER,
    )
}

As we can see, the logic above is pretty similar to what we’ve done before.

We mark our class with @RestController and @RequestMapping, functions with annotations matching HTTP Methods they are gonna handle, and also our path variables and request bodies.

When converting between models/requests/responses, we make use of extension functions, which are my favorite approach for mappers in Kotlin.

Lastly, whenever we want to return anything else than 200 OK, we use the ResponseStatusException, which is a clean way to do so.

If you would like to test this API now, then check out the following Postman collection.

Import Spring Security and JWT Library

Wonderful. At this point, we have everything we need to finally add Spring Security to our Spring Boot Kotlin project, and start implementing JWT authentication and authorization.

Update build.gradle.kts

As the first step, let’s add the following to the build.gradle.kts file:

dependencies {
	// other imports
	implementation("io.jsonwebtoken:jjwt-api:0.12.3")
	implementation("io.jsonwebtoken:jjwt-impl:0.12.3")
	implementation("io.jsonwebtoken:jjwt-jackson:0.12.3")
	implementation("org.springframework.boot:spring-boot-starter-security")
	testImplementation("org.springframework.security:spring-security-test")
}

As we can see, in order to secure our Spring Boot 3 REST API, we must add not only the Spring Security but also an additional library to deal with JWT tokens.

Although the Spring security is a must-have, please feel free to choose whatever JWT library suits you best (you can find a full list here). I have decided to go with io.jsonwebtoken which is the most popular Java library.

Sync and Rerun Project

Following, let’s sync our Gradle project and rerun our application.

Among other logs, we will see the following lines:

Using generated security password: 52d7d5b8-ce49-4d93-a4e1-721780290e58

This generated password is for development use only. Your security configuration must be updated before running your application in production.

Moreover, when we try to query our endpoints, we will get 401 Unauthorized for each request.

But what happened?

Well, whenever we add Spring Security to our Spring Boot project, the authentication gets enabled by default.

In other words, we can query our endpoint now using the basic access authentication with user as a username and the randomly generated password as the password.

As a proof, when we update the Authorization in our Postman collection, we will start seeing results again:

Create JWT Tokens

Although basic auth may be a good choice in some cases, in this tutorial, I would like to show you how to authenticate and authorize requests using JWT access tokens.

So, let’s start everything by implementing a service responsible for token operations.

Edit application.yaml file

As the first step, let’s navigate to the resources folder and edit the application.yaml file:

Note: when generating a new Spring Boot project, the application.properties file is created automatically. So before we start, let’s change the extension to yaml.

jwt:
  key: ${JWT_KEY}
  access-token-expiration: 3600000
  refresh-token-expiration: 86400000

As we can see, we introduce 3 custom properties: the key and expiration time (in milliseconds) for both access and refresh tokens.

The key is value will be sourced from the JWT_TOKEN environment variable, which is nothing else than a randomly generated String value. Later, we will see where and why we need it.

Important: vulnerable values should never be hardcoded when implementing a Spring Boot (and not only) application.

Regardless of the environment the app is running in, values should be stored securely and sourced to our application using environment variables.

Make Use Of @ConfigurationProperties

As the next step, let’s make use of the @ConfigurationProperties to easily convert our properties into Kotlin objects.

Let’s start by adding the configuration package and the JwtProperties class:

import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties("jwt")
data class JwtProperties(
  val key: String,
  val accessTokenExpiration: Long,
  val refreshTokenExpiration: Long,
)

If you’d like to learn more about @ConfigurationProperties, then I have another article you might want to check out later.

Additionally, let’s add the Configuration class:

import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration


@Configuration
@EnableConfigurationProperties(JwtProperties::class)
class Configuration

This way, we enable support for beans annotated with @ConfigurationProperties in our project.

Add TokenService

With all of that done, let’s add the TokenService class:

@Service
class TokenService(
  jwtProperties: JwtProperties
) {

  private val secretKey = Keys.hmacShaKeyFor(
    jwtProperties.key.toByteArray()
  )

  fun generate(
    userDetails: UserDetails,
    expirationDate: Date,
    additionalClaims: Map<String, Any> = emptyMap()
  ): String =
    Jwts.builder()
      .claims()
      .subject(userDetails.username)
      .issuedAt(Date(System.currentTimeMillis()))
      .expiration(expirationDate)
      .add(additionalClaims)
      .and()
      .signWith(secretKey)
      .compact()

  fun isValid(token: String, userDetails: UserDetails): Boolean {
    val email = extractEmail(token)

    return userDetails.username == email && !isExpired(token)
  }

  fun extractEmail(token: String): String? =
    getAllClaims(token)
      .subject

  fun isExpired(token: String): Boolean =
    getAllClaims(token)
      .expiration
      .before(Date(System.currentTimeMillis()))

  private fun getAllClaims(token: String): Claims {
    val parser = Jwts.parser()
      .verifyWith(secretKey)
      .build()

    return parser
      .parseSignedClaims(token)
      .payload
  }
}

As we can see, this class exposes functions, which we can use to deal with JWT access and refresh tokens.

Let’s walk quickly through our logic:

private val secretKey = Keys.hmacShaKeyFor(
  jwtProperties.key.toByteArray()
)

The secretKey is nothing else than an instance of SecretKey, which we will use to sign and verify JWT tokens in our system. In our case, we will use the HMAC-SHA algorithm based on the random key we provided to our project.

fun generate(
  userDetails: UserDetails,
  expirationDate: Date,
  additionalClaims: Map<String, Any> = emptyMap()
): String =
  Jwts.builder()
    .claims()
    .subject(userDetails.username)
    .issuedAt(Date(System.currentTimeMillis()))
    .expiration(expirationDate)
    .add(additionalClaims)
    .and()
    .signWith(secretKey)
    .compact()

The generate function is responsible for creating a serialized, URL-safe String with JWT tokens. We set the subject, expiration date, and additional claims based on the arguments passed to it.

Lastly, we sign the token using the SecretKey instance created in the previous step.

Additionally, we provide more functions which we will use later to extract values from tokens and validate them:

fun isValid(token: String, userDetails: UserDetails): Boolean {
  val email = extractEmail(token)

  return userDetails.username == email && !isExpired(token)
}

fun extractEmail(token: String): String? =
  getAllClaims(token)
    .subject

fun isExpired(token: String): Boolean =
  getAllClaims(token)
    .expiration
    .before(Date(System.currentTimeMillis()))

private fun getAllClaims(token: String): Claims {
  val parser = Jwts.parser()
    .verifyWith(secretKey)
    .build()

  return parser
    .parseSignedClaims(token)
    .payload
}

Implement Custom UserDetailsService

As the next step, let’s introduce a custom implementation of UserDetailsService.

But what exactly is UserDetailsService and UserDetails?

Well, the UserDetails represents the core user information. In our case, we will use the default implementation called User, which holds the default information, such as username, password, and a collection of granted authorities (roles).

The UserDetailsService is nothing else than an interface used to load user-specific data. It is used by Spring Security to interact with our data source and validate users during authentication.

With that said, let’s add a new class- CustomUserDetailsService– to the service package:

import com.codersee.jwtauth.repository.UserRepository
import org.springframework.security.core.userdetails.User
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import org.springframework.stereotype.Service

typealias ApplicationUser = com.codersee.jwtauth.model.User

@Service
class CustomUserDetailsService(
  private val userRepository: UserRepository
) : UserDetailsService {

  override fun loadUserByUsername(username: String): UserDetails =
    userRepository.findByEmail(username)
      ?.mapToUserDetails()
      ?: throw UsernameNotFoundException("Not found!")

  private fun ApplicationUser.mapToUserDetails(): UserDetails =
    User.builder()
      .username(this.email)
      .password(this.password)
      .roles(this.role.name)
      .build()
}

As we can see, both the username and email in our system refer to the same thing, which is used to uniquely identify users.

And in order to fetch UserDetails we must find the user in our repository and map it to the User instance.

Additionally, we make use of the typealias which is a great way to avoid fully qualified name (we have both User in our model package and User from Spring Security

Update Configuration

With that done, let’s get back to the Configuration class and register a few beans:

import com.codersee.jwtauth.repository.UserRepository
import com.codersee.jwtauth.service.CustomUserDetailsService
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.AuthenticationProvider
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder

@Configuration
@EnableConfigurationProperties(JwtProperties::class)
class Configuration {

  @Bean
  fun userDetailsService(userRepository: UserRepository): UserDetailsService =
    CustomUserDetailsService(userRepository)

  @Bean
  fun encoder(): PasswordEncoder = BCryptPasswordEncoder()

  @Bean
  fun authenticationProvider(userRepository: UserRepository): AuthenticationProvider =
    DaoAuthenticationProvider()
      .also {
        it.setUserDetailsService(userDetailsService(userRepository))
        it.setPasswordEncoder(encoder())
      }

  @Bean
  fun authenticationManager(config: AuthenticationConfiguration): AuthenticationManager =
    config.authenticationManager
}

Firstly, we must register the bean of type UserDetailsService, which we introduced in the previous step.

Following, we register a PasswordEncoder. To put it simply, we should never store passwords in plain text. They should be always encrypted, or hashed. In this tutorial, we will use the BCrypt strong hashing function for that purpose.

Following, we must provide the AuthenticationProvider and configure which UserDetailsService we will use and the password encoder.

Update UserRepository

In the previous step, I mentioned that we should never store passwords in plain text.

So, to fix that, let’s get back to the UserRepository and make the necessary changes:

@Repository
class UserRepository(
  private val encoder: PasswordEncoder
) {

  private val users = mutableSetOf(
    User(
      id = UUID.randomUUID(),
      email = "email-1@gmail.com",
      password = encoder.encode("pass1"),
      role = Role.USER,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-2@gmail.com",
      password = encoder.encode("pass2"),
      role = Role.ADMIN,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-3@gmail.com",
      password = encoder.encode("pass3"),
      role = Role.USER,
    ),
  )

  fun save(user: User): Boolean {
    val updated = user.copy(password = encoder.encode(user.password))

    return users.add(updated)
  }
}

As we can see, after this step both our predefined users and all users which we will create will have their passwords hashed.

Implement AuthenticationFilter

Uff, quite a lot of preparation must be done before we secure our Spring Boot 3 Kotlin app with JWT tokens, isn’t it?

But don’t worry, we’re almost there.

As the next step, let’s navigate to the config package and introduce our custom Filter:

import com.codersee.jwtauth.service.CustomUserDetailsService
import com.codersee.jwtauth.service.TokenService
import jakarta.servlet.FilterChain
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource
import org.springframework.stereotype.Component
import org.springframework.web.filter.OncePerRequestFilter

@Component
class JwtAuthenticationFilter(
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
) : OncePerRequestFilter() {

  override fun doFilterInternal(
    request: HttpServletRequest,
    response: HttpServletResponse,
    filterChain: FilterChain
  ) {
    val authHeader: String? = request.getHeader("Authorization")

    if (authHeader.doesNotContainBearerToken()) {
      filterChain.doFilter(request, response)
      return
    }

    val jwtToken = authHeader!!.extractTokenValue()
    val email = tokenService.extractEmail(jwtToken)

    if (email != null && SecurityContextHolder.getContext().authentication == null) {
      val foundUser = userDetailsService.loadUserByUsername(email)

      if (tokenService.isValid(jwtToken, foundUser))
        updateContext(foundUser, request)

      filterChain.doFilter(request, response)
    }
  }

  private fun String?.doesNotContainBearerToken() =
    this == null || !this.startsWith("Bearer ")

  private fun String.extractTokenValue() =
    this.substringAfter("Bearer ")

  private fun updateContext(foundUser: UserDetails, request: HttpServletRequest) {
    val authToken = UsernamePasswordAuthenticationToken(foundUser, null, foundUser.authorities)
    authToken.details = WebAuthenticationDetailsSource().buildDetails(request)
    SecurityContextHolder.getContext().authentication = authToken
  }

}

I know, quite a lot of logic, but I’ll explain it step-by-step in a moment.

But before that, let’s understand what are Filters in Spring Framework.

Well, every request made to our Spring Framework application goes through the filter chain, where each filter in the chain can perform some operations on the request or response.

In our case, we want to use this feature to authenticate requests made to our REST API. We want to check whether a user sent a JWT token and validate it, and if everything is fine, we want to update the Spring Security Context.

And that’s exactly what’s happening in the code above.

Firstly, we check if the request contains an Authorization header. If no, we do not proceed with this function and we simply pass the request down the filter chain.

Nextly, we extract the JWT token. A valid Authorization header value consists of the Bearer <JWT>, so we must extract the token itself.

Following, we read the email value from the token. And when we make sure it is not null and there’s no previously authenticated principal in the security context, we fetch the UserDetails, which we then use to validate them with the token.

Lastly, we simply update the security context in our system with foundUser (which is UserDetails) and authorities (which, in our case will be either ADMIN or USER).

To sum up, this function will be invoked once per each request. In simple terms, it will check the JWT token and if everything is fine, it will update the Spring Security context with information about user and its roles.

Add Security Configuration

At this point, we did everything we needed to to in order to authenticate the user.

In this step, we will learn how to authorize him.

And to do so, let’s introduce a new class- SecurityConfiguration – in the config package:

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.HttpMethod
import org.springframework.security.authentication.AuthenticationProvider
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.web.DefaultSecurityFilterChain
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter

@Configuration
@EnableWebSecurity
class SecurityConfiguration(
  private val authenticationProvider: AuthenticationProvider
) {

  @Bean
  fun securityFilterChain(
    http: HttpSecurity,
    jwtAuthenticationFilter: JwtAuthenticationFilter
  ): DefaultSecurityFilterChain {
    http
      .csrf { it.disable() }
      .authorizeHttpRequests {
        it
          .requestMatchers("/api/auth", "api/auth/refresh", "/error")
          .permitAll()
          .requestMatchers(HttpMethod.POST, "/api/user")
          .permitAll()
          .requestMatchers("/api/user**")
          .hasRole("ADMIN")
          .anyRequest()
          .fullyAuthenticated()
      }
      .sessionManagement {
        it.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
      }
      .authenticationProvider(authenticationProvider)
      .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter::class.java)

    return http.build()
  }
}

As we can see, the above config exposes a new bean of type DefaultSecurityFilterChain.

To put it simply, this is the way we can modify the default chain by adding, removing, or replacing filters to tailor the security configuration according to our needs.

The first thing we do is disable the CSRF protection. It’s enabled by default, and in most cases not needed (but in real-life projects, please learn a bit more about CSRF attacks and whether your codebase is vulnerable).

Following, we configure the authorization. We can clearly see that requests to “/api/auth”, “api/auth/refresh”, “/error”, and POST requests to “/api/user” will be accessible without a token. And that’s correct- we cannot require a valid access token for users, who want to sign in, who want to create a new account, and when the API client wants to refresh the token.

And if you are wondering why is the “/error” in this list, too, then here comes the answer. It is because of the way Spring handles errors internally. Without that, every exception we throw in our codebase will return 403 Forbidden, instead of the HTTP status code we provided.

When it comes to the rest of the “/api/user” requests- we want to allow only users with role ADMIN.

And what with the rest of the requests? Well, we want them to be accessed only by fully authenticated users. But what does it mean? In our, stateless REST API, it means simply that every user with a valid JWT token will be able to access them (regardless of his role).

After that, we informed Spring that it should never create a HttpSession (we want our security to be stateless) and that it should never use it to obtain the SecurityContext.

And lastly, we register our CustomAuthenticationProvider and let Spring Security know that JwtAuthenticationFilter we implemented previously should be added before the default UsernamePasswordAuthenticationFilter (the one that required us to specify basic auth).

Expose Login Endpoint – Generate Access Token

With all of that done, we can finally expose the endpoint, which will be used by our REST API consumers to get the JWT access token.

Let’s create the config.auth package and add a new controller class:

import com.codersee.jwtauth.service.AuthenticationService
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/auth")
class AuthController(
  private val authenticationService: AuthenticationService
) {

  @PostMapping
  fun authenticate(
    @RequestBody authRequest: AuthenticationRequest
  ): AuthenticationResponse =
    authenticationService.authentication(authRequest)

}

As we can see, this controller uses AuthenticationService which we will implement in a moment.

But before we do so, let’s add the AuthenticationRequest:

data class AuthenticationRequest(
  val email: String,
  val password: String,
)

And the response class:

data class AuthenticationResponse(
  val accessToken: String,
)

After that, let’s get back to the service package and implement a service, which will be responsible for authentication and token generation:

import com.codersee.jwtauth.controller.auth.AuthenticationRequest
import com.codersee.jwtauth.controller.auth.AuthenticationResponse
import com.codersee.jwtauth.controller.config.JwtProperties
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Service
import java.util.*

@Service
class AuthenticationService(
  private val authManager: AuthenticationManager,
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
  private val jwtProperties: JwtProperties,
) {

  fun authentication(authenticationRequest: AuthenticationRequest): AuthenticationResponse {
    authManager.authenticate(
      UsernamePasswordAuthenticationToken(
        authenticationRequest.email,
        authenticationRequest.password
      )
    )

    val user = userDetailsService.loadUserByUsername(authenticationRequest.email)

    val accessToken = createAccessToken(user)

    return AuthenticationResponse(
      accessToken = accessToken,
    )
  }

  private fun createAccessToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getAccessTokenExpiration()
  )

  private fun getAccessTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.accessTokenExpiration)

}

As we can see, the first thing we do is invoke the authenticate method from AuthenticationManager.

If the email and password values don’t match with any of the users in our system, the authenticate method will throw AuthenticationException and the API will return 403 Forbidden.

On the other hand, when they match, we will fetch the UserDetails and use it to generate a JWT token with an expiration time set in application.yaml

At the moment, I highly encourage you to run our application and try to call endpoints with different cases. If you would like to use a ready-to-go Postman collection, then you can find one with all endpoints in the next chapter about refresh tokens.

JWT Refresh Token

Excellent! At this point, our REST API is properly secured and utilizing the JWT access tokens.

But depending on your needs, you may want to introduce the JWT refresh tokens to the system.

Introduce New Endpoint

Firstly, let’s introduce a new endpoint and update our response classes.

Let’s start by adding a new TokenResponse:

data class TokenResponse(
  val token: String
)

We will use this class to return the refreshed access token.

Following, let’s make the necessary changes to the AuthenticationResponse:

data class AuthenticationResponse(
  val accessToken: String,
  val refreshToken: String,
)

As we can see, the refreshToken value will be returned when a user authenticates successfully along with the JWT token value.

After that, let’s add the RefreshTokenRequest, which will be used to deserialize refresh token sent by a user:

data class RefreshTokenRequest(
  val token: String
)

Great!

At this point, we can add a new endpoint:

  @PostMapping("/refresh")
  fun refreshAccessToken(
    @RequestBody request: RefreshTokenRequest
  ): TokenResponse =
    authenticationService.refreshAccessToken(request.token)
      ?.mapToTokenResponse()
      ?: throw ResponseStatusException(HttpStatus.FORBIDDEN, "Invalid refresh token.")

  private fun String.mapToTokenResponse(): TokenResponse =
    TokenResponse(
      token = this
    )

Don’t worry about the missing refreshAccessToken method, we will get back to it in a moment.

Implement Refresh Token Repository

As the next step, let’s go to the repository package and introduce the RefreshTokenRepository:

import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Component

@Component
class RefreshTokenRepository {

  private val tokens = mutableMapOf<String, UserDetails>()

  fun findUserDetailsByToken(token: String) : UserDetails? =
    tokens[token]

  fun save(token: String, userDetails: UserDetails) {
    tokens[token] = userDetails
  }

}

As we can see, this class will be responsible for persisting and retrieving refresh tokens.

Along with our tokens, we will store the associated UserDetails instances, so that later we could match the associated subject (email).

Edit AuthenticationService

As the last thing, we must get back to the AuthenticationService and make the necessary changes:

import com.codersee.jwtauth.controller.auth.AuthenticationRequest
import com.codersee.jwtauth.controller.auth.AuthenticationResponse
import com.codersee.jwtauth.controller.config.JwtProperties
import com.codersee.jwtauth.repository.RefreshTokenRepository
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Service
import java.util.*

@Service
class AuthenticationService(
  private val authManager: AuthenticationManager,
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
  private val jwtProperties: JwtProperties,
  private val refreshTokenRepository: RefreshTokenRepository,
) {

  fun authentication(authenticationRequest: AuthenticationRequest): AuthenticationResponse {
    authManager.authenticate(
      UsernamePasswordAuthenticationToken(
        authenticationRequest.email,
        authenticationRequest.password
      )
    )

    val user = userDetailsService.loadUserByUsername(authenticationRequest.email)

    val accessToken = createAccessToken(user)
    val refreshToken = createRefreshToken(user)

    refreshTokenRepository.save(refreshToken, user)

    return AuthenticationResponse(
      accessToken = accessToken,
      refreshToken = refreshToken
    )
  }

  fun refreshAccessToken(refreshToken: String): String? {
    val extractedEmail = tokenService.extractEmail(refreshToken)

    return extractedEmail?.let { email ->
      val currentUserDetails = userDetailsService.loadUserByUsername(email)
      val refreshTokenUserDetails = refreshTokenRepository.findUserDetailsByToken(refreshToken)

      if (!tokenService.isExpired(refreshToken) && refreshTokenUserDetails?.username == currentUserDetails.username)
        createAccessToken(currentUserDetails)
      else
        null
    }
  }

  private fun createAccessToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getAccessTokenExpiration()
  )

  private fun createRefreshToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getRefreshTokenExpiration()
  )

  private fun getAccessTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.accessTokenExpiration)

  private fun getRefreshTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.refreshTokenExpiration)
}

Let’s summarize what exactly has changed here.

Firstly, we imported the RefreshTokenRepository, so that we could persist new tokens and retrieve the saved ones.

Moreover, we must generate a new refresh token whenever a user authenticates successfully. And that’s why we added the getRefreshTokenExpiration function and two additional lines in the authentication method.

When it comes to the refresh token flow, it can be summarized in the following steps:

1. We extract the user email from the passed refresh token.
2. If this step is completed successfully, we fetch the current user details by the value.
3. After that, we look for the persisted user details with the refresh token.
4. Lastly, if the refresh token is not expired and the email from JWT subject matches the current user details, then a new access token is generated for that user.
5. Otherwise, we return null, which will be translated to 403 Forbidden in our controller.

And basically, that’s all 🙂

If you would like to use a ready-to-go Postman collection with auh headers, then you can find it right here.

Summary

And that’s all for this tutorial in which we have learned how to secure the REST API with Spring Boot 3 (Spring Security 6) with JWT access and refresh tokens and Kotlin. Good job!

If you would like to get the source code for this lesson, then check out this GitHub repository.

Lastly, if you enjoyed this one, then do not forget to leave a comment and check out my Complete Kotlin Course 🙂

The post Spring Boot 3 (Spring Security 6) with Kotlin & JWT appeared first on Codersee blog- Kotlin on the backend.

In this article, I will show you four ideas on how to solve this issue.

Please keep in mind that all of them are workarounds, and if you came up with something even better, then do not forget to share in the comments🙂

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Problem

To be on the same page, let’s take a quick look at a simple Spring Boot configuration with @ConfigurationProperties.

Firstly, let’s navigate to the application.yaml file:

example:
  some-property: ${SOME_VARIABLE}

As we can see, we defined a new property inside our config file for which the value should be set from the environment variable named SOME_VARIABLE.

Following, let’s introduce the @ConfigurationProperties class:

@ConfigurationProperties(prefix = "example")
data class ExampleConfigurationProperties(
  val someProperty: String
)

With this code, we expect that Spring Framework will read all properties defined in the configuration file and inject values into the matching properties.

Note: Spring recognizes the kebab case (some-property) and matches it with the property using camel case (someProperty)

After that, we need to explicitly inform Spring about our configuration properties class:

@Configuration
@EnableConfigurationProperties(ExampleConfigurationProperties::class)
class Config

Lastly, we must add a class, which injects the ExampleConfigurationProperties and prints out the value of someProperty:

@Component
class SomeComponent(
  private val properties: ExampleConfigurationProperties
) {

  @PostConstruct
  fun init() {
    println(properties.someProperty)
  }

}

Finally, when we run our application without the SOME_VARIABLE environment variable missing, we will see the following output:

${SOME_VARIABLE}

A bit counterintuitive, right?

It would seem pretty obvious, that if we declare someProperty as a non-nullable String and environment variable is missing, our Spring Boot app should fail to start.

Unfortunately, that’s not the case when using @ConfigurationProperties and Spring will default the String value to the name of placeholder.

Moreover, at the moment of writing, there is no built-in way we could enforce that.

Solution With Spring Validation

As a first solution (or rather workaround), let’s add the spring-boot-starter-validation to our project:

implementation("org.springframework.boot:spring-boot-starter-validation")

Nextly, let’s instruct Spring that it should default to the blank String value whenever our environment variable is missing:

example:
  some-property: ${SOME_VARIABLE:}

After that let’s modify our configuration properties class:

import jakarta.validation.constraints.NotBlank
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.validation.annotation.Validated

@ConfigurationProperties(prefix = "example")
@Validated
data class ExampleConfigurationProperties(
  @field:NotBlank val someProperty: String
)

As we can see, with a combination of @Validated and @NotBlank, we ask Spring Framework to check if the value is not null and contains at least one non-whitespace character.

Note: in Kotlin, we must use the @field: to annotate Java field.

If you would like to learn this, and many more then check out my Kotlin course.

Finally, when we try to run our application, we will see the following:

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'example' to com.codersee.properties.ExampleConfigurationProperties failed:

    Property: example.someProperty
    Value: ""
    Origin: class path resource [application.yaml] - 2:18
    Reason: must not be blank


Action:

Update your application's configuration


Process finished with exit code 1

And maybe this solution is nott ideal, but it does its job.

And it is neat. Not only does the application not start, but also whenever the environment variable for our @ConfigurationProperties is missing, we will see a meaningful message that will speed up the debugging process.

Custom ApplicationRunner Idea

Another solution for our problem does not require any additional dependencies added to our project.

Let’s take a look at the following implementation of ApplicationRunner:

import org.springframework.boot.ApplicationArguments
import org.springframework.boot.ApplicationRunner
import org.springframework.stereotype.Component

@Component
class MyApplicationRunner : ApplicationRunner {

  companion object {
    private val requiredVariables = setOf(
      "SOME_VARIABLE"
    )
  }

  override fun run(args: ApplicationArguments) {
    requiredVariables.forEach {
      System.getenv(it)
        ?: throw MissingEnvVariableException(it)
    }
  }

}

class MissingEnvVariableException(variableName: String) :
  RuntimeException("Application failed to start. Missing environment variable: $variableName")

This time, we introduce our set of required environment variables and check if they are present.

Whenever it’s missing, we throw the MissingEnvVariableException and prevent the app from starting:

java.lang.IllegalStateException: Failed to execute ApplicationRunner
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:765) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.callRunners(SpringApplication.java:752) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:319) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1295) ~[spring-boot-3.1.3.jar:3.1.3]
	at com.codersee.properties.PropertiesApplicationKt.main(PropertiesApplication.kt:13) ~[main/:na]
Caused by: com.codersee.properties.MissingEnvVariableException: Application failed to start. Missing environment variable: SOME_VARIABLE
	at com.codersee.properties.MyApplicationRunner.run(MyApplicationRunner.kt:19) ~[main/:na]
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:762) ~[spring-boot-3.1.3.jar:3.1.3]
	... 5 common frames omitted


Process finished with exit code 1

This solution gives us a bit more control and allows us to customize the behavior better.

Would we like to log an error, or maybe send an alert request? No problem. With a few lines of code, we can easily achieve that.

Nevertheless, with this approach, we introduce a new, separate place in the code we need to remember every time we want to add a new environment variable. And this might be easily forgotten in bigger projects.

Fix With @Conditional

As the next step, let’s take a look at the approach with @Conditional annotation, which slightly reduces the chance of forgetting about additional checks.

Firstly, let’s add a new class called RequiredEnvVariablesCondition:

class RequiredEnvVariablesCondition : Condition {

  private val logger: Logger = LogManager.getLogger(this::class.java)

  companion object {
    private val requiredVariables = setOf(
      "SOME_VARIABLE"
    )
  }

  override fun matches(context: ConditionContext, metadata: AnnotatedTypeMetadata): Boolean {
    val isEnvVariableMissing = requiredVariables
      .any { envVariableName ->
        val isMissing = System.getenv(envVariableName) == null

        if (isMissing)
          logger.error("Variable $envVariableName is missing!")

        isMissing
      }

    return !isEnvVariableMissing
  }

}

As we can see, this logic is pretty similar to what we’ve done previously.

Every time the environment variable is missing, we log an error message and return false from the overridden matches function.

So with that done, we can annotate our config class with @Conditional:

import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Conditional
import org.springframework.context.annotation.Configuration

@Configuration
@EnableConfigurationProperties(ExampleConfigurationProperties::class)
@Conditional(RequiredEnvVariablesCondition::class)
class Config

This time, we will get the following output if we try to run the app without passing the environment variable:

2023-09-14T07:20:58.813+02:00 ERROR 16188 --- [           main] c.c.p.RequiredEnvVariablesCondition      : Variable SOME_VARIABLE is missing!

***************************
APPLICATION FAILED TO START
***************************

Description:

Parameter 0 of constructor in com.codersee.properties.SomeComponent required a bean of type 'com.codersee.properties.ExampleConfigurationProperties' that could not be found.


Action:

Consider defining a bean of type 'com.codersee.properties.ExampleConfigurationProperties' in your configuration.


Process finished with exit code 1

(Bonus) Use @Value Instead

There’s no doubt that @ConfigurationProperties helps us write cleaner code and better organize configuration in our codebase. Moreover, we can effortlessly add new values to the project with this approach.

However, in some cases, we should consider using @Value annotation instead:

package com.codersee.properties

import jakarta.annotation.PostConstruct
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component

@Component
class SomeComponent(
  @Value("\${example.some-property}") private val someProperty: String
) {

  @PostConstruct
  fun init() {
    println(someProperty)
  }
}

This time, we can completely get rid of @Configuration and @ConfigurationProperties classes.

Instead of injecting a whole configuration object, we focus on the desired config value.

And whenever it’s missing, we get the following output out of the box:

Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
2023-09-14T07:16:43.532+02:00 ERROR 18412 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'someComponent' defined in file: Unexpected exception during bean creation
...
Caused by: java.lang.IllegalArgumentException: Could not resolve placeholder 'SOME_VARIABLE' in value "${SOME_VARIABLE}"
...
Process finished with exit code 1

As we can see, our Spring Boot app won’t start if the environment variable is missing and we will get a meaningful message.

But again, we should use @Value wisely and most of the time @ConfigurationProperties can be a better approach.

Summary

And that’s all for this article on how to fail a Spring Boot app on missing environment variables.

As I mentioned in the beginning- these are just a few ideas that came to my mind. If you figure out some other way, then please share them in the comments section below.

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

Thank you for reading, and see you next time! 🙂

The post Fail Spring Boot App on Missing Environment Variables appeared first on Codersee blog- Kotlin on the backend.

Hello ! 🙂 Continuing the DSL topic, I would like to show you how to expose a REST API using Spring Boot 3, Kotlin, bean definition, and router DSL.

In my previous article, I showed you how the router DSL works and how to expose endpoints manually without needing any web-related annotations, like @RequestMapping, @RestController, @RequestBody, etc…

But is it possible to eliminate the annotations when defining beans? Yes, and in this article, I will prove to you that it’s possible to expose a REST API without any annotations, like @Component or any specialization.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

2. Project Setup

Firstly, let’s navigate to https://start.spring.io/ and generate a new project:

As we can see, in order to expose a REST API with Spring Boot 3 and Kotlin DSL, we don’t have to add any additional dependencies. The only one is the Spring Web, which lets us build web applications.

Following, please import the project to your favorite IDE (like IntelliJ).

3. Add Models

Nextly, let’s create the model package and add 3 data classes to our application:

• User, which will transfer the data between the app and the data source,
• UserDTO, which will be serialized to JSON responses,
• and ErrorResponse, shipping information about backend errors.

// User.kt
data class User(
  val id: Long? = null,
  val email: String,
  val name: String,
  val age: Int
)

// UserDTO.kt
data class UserDTO(
  val email: String,
  val name: String,
  val age: Int
)

// ErrorResponse.kt
data class ErrorResponse(
  val message: String
)

4. Implement a Repository

As the next step, let’s create a repository package.

[elementor-template id=”9007393″]

4.1 Add UserRepository Interface

Following, let’s introduce a UserRepository:

interface UserRepository {
  fun create(user: User): User
  fun findAll(): List<User>
  fun findById(id: Long): User?
  fun updateById(id: Long, user: User): User?
  fun deleteById(id: Long)
}

And although oftentimes I skip this part for the simplicity of my tutorials, you will later see that working with interfaces, rather than implementations gives us much more flexibility. And in real-life scenarios, we should consider using them.

4.2 Add Implementation

So nextly, let’s add the UserCrudRepository to the codebase:

class UserCrudRepository(
  private val dataSource: MutableMap<Long, User>
) : UserRepository {

  override fun create(user: User): User {
    val lastId = this.dataSource.keys.max()
    val incrementedId = lastId + 1
    val updatedUser = user.copy(id = incrementedId)

    this.dataSource[incrementedId] = updatedUser

    return updatedUser
  }

  override fun findAll(): List<User> =
    this.dataSource.values
      .toList()

  override fun findById(id: Long): User? =
    this.dataSource[id]

  override fun updateById(id: Long, user: User): User? =
    this.dataSource[id]
      ?.let { foundUser -> 
        val updatedUser = user.copy(id = foundUser.id)
        this.dataSource[id] = updatedUser
        updatedUser
      }

  override fun deleteById(id: Long) {
    this.dataSource.remove(id)
  }
}

As we can see, this class is just a dummy in-memory database, which will be operating on the dataSource map provided as a constructor argument.

4.3 Implement DataSource

With that being done, let’s create a new object called DataSource (can go to the config package):

object DataSource {

  val devDataSource: MutableMap<Long, User> = mutableMapOf(
    1L to User(1L, "email-1@gmail.com", "Name 1", 22),
    2L to User(2L, "email-2@gmail.com", "Name 2", 43),
    3L to User(3L, "email-3@gmail.com", "Name 3", 26),
    4L to User(4L, "email-4@gmail.com", "Name 4", 50)
  )

  val prodDataSource: MutableMap<Long, User> = mutableMapOf(
    1L to User(1L, "prod-email-1@gmail.com", "Name 1", 22),
    2L to User(2L, "prod-email-2@gmail.com", "Name 2", 43),
    3L to User(3L, "prod-email-3@gmail.com", "Name 3", 26),
    4L to User(4L, "prod-email-4@gmail.com", "Name 4", 50)
  )

}

Well, in our application we will be dealing with dummy data.

However, in real life instead of two maps implementations, we would rather have a few implementations of UserRepository, for example:

• one, in-memory, which could be used for local development and testing,
• the second, “real”, one, responsible for database connection.

Either way, the purpose of this tutorial is to learn a bit more about Kotlin with bean definition DSL, and this setup will be useful in our considerations.

5. Configure Routing

In order to expose REST endpoints with Kotlin route DSL, we need to add two things:

• UserHandler– which normally would be a UserController when working with annotations,
• custom RouteFunctionDSL– responsible for URL mappings.

5.1 Add UserHandler

Firstly, let’s add a handler package and implement the UserHandler:

class UserHandler(
  private val userRepository: UserRepository
) {

  fun createUser(
    request: ServerRequest
  ): ServerResponse {
    val userRequest = request.body(UserDTO::class.java)

    val createdUserResponse = userRepository.create(
      user = userRequest.toModel()
    )
      .toDTO()

    return ServerResponse.ok()
      .body(createdUserResponse)
  }

  fun findAllUsers(
    request: ServerRequest
  ): ServerResponse {
    val usersResponses = userRepository.findAll()
      .map(User::toDTO)

    return ServerResponse.ok()
      .body(usersResponses)
  }

  fun findUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    val userResponse = userRepository.findById(id)
      ?.toDTO()

    return userResponse
      ?.let { response ->
        ServerResponse.ok()
          .body(response)
      }
      ?: notFoundResponse(id)
  }

  fun updateUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    val userRequest = request.body(UserDTO::class.java)

    val updatedUser = userRepository.updateById(
      id = id,
      user = userRequest.toModel()
    )

    return updatedUser
      ?.let { response ->
        ServerResponse.ok()
          .body(response)
      }
      ?: notFoundResponse(id)
  }

  fun deleteUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    userRepository.deleteById(id)

    return ServerResponse.noContent()
      .build()
  }

  private fun badRequestResponse(reason: String): ServerResponse =
    ServerResponse.badRequest()
      .body(
        ErrorResponse(reason)
      )

  private fun notFoundResponse(id: Long): ServerResponse =
    ServerResponse.badRequest()
      .body(
        ErrorResponse("User with id: $id was not found.")
      )

}

private fun UserDTO.toModel(): User =
  User(
    email = this.email,
    name = this.name,
    age = this.age
  )

private fun User.toDTO(): UserDTO =
  UserDTO(
    email = this.email,
    name = this.name,
    age = this.age
  )

As we can see, the handler has only one parameter of the UserRepository  type. Thanks do that, we are not coupled with any implementation. Moreover, we gained flexibility and we can provide the implementation even on the fly when configuring beans.

Another interesting thing is the usage of ServerRequests and ServerResponses. When working with Spring Boot and Kotlin routes DSL, that’s how we deal with incoming requests and responses. And although for more details I redirect you to my previous article about this topic, I wanted to mention this because of one thing. As you can see- instead of throwing exceptions, which then Spring would translate to HTTP responses, we have the possibility to return our custom payload (and status codes, as well).

5.2 Implement Routing

Nevertheless, handler implementation is not sufficient. We have to instruct Spring about how HTTP requests should be handled.

To do so, let’s add the Routes.kt file inside the config package:

fun appRouter(userHandler: UserHandler) = router {
  "/api".nest {
    "/users".nest {
      POST(userHandler::createUser)
      GET(userHandler::findAllUsers)
      GET("/{id}", userHandler::findUserById)
      PUT("/{id}", userHandler::updateUserById)
      DELETE("/{id}", userHandler::deleteUserById)
    }
  }
}

The appRouter function has one parameter of the UserHandler type, which we then use to provide references to functions inside it.

It’s worth mentioning that function references in Kotlin are an interesting syntactic sugar. However, if you prefer not to use them, you can always simply make use of brackets:

POST { request -> userHandler.createUser(request) }

6. Kotlin Bean Definition DSL

With all of that being done, we can finally learn how the Kotlin bean definition DSL work with Spring Boot 3.

6.1 Implement BeansConfig

Firstly, let’s add a new file called BeansConfig.kt inside the config package:

val beans = beans {
  // beans definitions
}

The beans {} is nothing else than a function, which leverages the concept of type-safe builders.

Secondly, let’s add the BeansConfig class:

class BeansConfig : ApplicationContextInitializer<GenericApplicationContext> {

  override fun initialize(context: GenericApplicationContext) =
    beans.initialize(context)

}

In order to register the beans in our application context, we have to invoke the initialize().

Lastly, we need to make Spring aware of our initializer in application.yaml:

context:
  initializer:
    classes: com.codersee.kotlindsl.config.BeansConfig

6.2 Autowiring By Type

As the next step, let’s see how we can define UserHandler and router beans and instruct Spring to autowire by type:

bean<UserHandler>()
bean(::appRouter)

As we can see, we don’t even have to specify the types of particular parameters and Spring will take care of that automatically.

Moreover, with callable reference, we can define a bean with the appRouter top-level function.

6.3 Explicitly Specify Bean Type

Of course, if we would like to specify the type of the bean manually or wire by name, then we can do it, as well:

bean("myHandlerBean") {
  UserHandler(ref())
}
bean {
  appRouter(
    ref("myHandlerBean")
  )
}

And this time we simply make use of the ref function, which is responsible for getting a reference to beans by type (line 2), or by type and name (line 6).

6.4 Conditional Beans Based On Profile

Following, let’s see how we can differentiate the data source based on the profile property:

profile("dev") {
  bean {
    UserCrudRepository(devDataSource)
  }
}

profile("prod") {
  bean {
    UserCrudRepository(prodDataSource)
  }
}

With this approach, beans defined inside the profile() won’t be created unless the specified profile is active.

Of course, we can activate profiles, for example inside the application.yaml:

spring:
  profiles:
    active: dev

6.5 Define Additional Beans Properties

Following, let’s see how we can customize bean definitions:

bean(
  name = "userHandler",
  scope = BeanDefinitionDsl.Scope.SINGLETON,
  isLazyInit = true,
  isPrimary = true,
  isAutowireCandidate = true,
  initMethodName = "",
  destroyMethodName = "",
  description = "description",
  role = BeanDefinitionDsl.Role.APPLICATION
)

As we can see, all parameters of the bean function have default values assigned.

Nevertheless, if we would like to set any values explicitly, then we can do it with ease.

6.6 Reading Environment Variables

As the last thing, let’s see how we can read environment variables:

val someVariable = env.systemEnvironment["SOME_VARIABLE"]

The systemEnvironment is nothing else than a Map<String, Object> instance, which is a result of System.getenv() invocation.

7. Spring Boot 3 Kotlin DSL Summary

And that’s all for this tutorial about how to implement a REST API without annotations using Spring Boot 3, Kotlin bean definition, and router DSL.

I’m happy to hear your feedback– trust me, such a simple comment can motivate a lot and help me to work on my weaknesses 🙂

Of course, if you would like to see the source code for this article, then you can find it in this GitHub repository.

The post Spring Boot 3 With Kotlin DSL. REST API Without Annotations appeared first on Codersee blog- Kotlin on the backend.