Awesome APIs with Kotlin, Spring 5 and Swagger

Early last year, Spring announced official support for Kotlin in Spring Framework 5. The news was welcome and exciting, particularly with respect to technologies like Spring Webflux, Project Reactor, and Spring functional, areas where Kotlin very much shines.

In this article, I will describe how to bootstrap a new Spring 5 project that integrates Kotlin, Spring Webflux functional, Project Reactor, Swagger, Gradle, and JUnit using kotlin-swagger-spring-functional-template. The template includes two sample REST endpoints and providesinteractive API documentation and automatic request validation.

You can view the complete template’s source code on GitHub or try the live demo on IBM Cloud.

Before we get started, let’s look at the technologies behind the template project.

• Kotlin — Statically typed programming language for modern multiplatform applications.
• Spring 5 Webflux — The module contains support for reactive HTTP and WebSocket clients as well as for reactive server web applications including REST, HTML browser, and WebSocket style interactions.
• Project Reactor — Reactor is a fourth-generation Reactive library for building non-blocking applications on the JVM based on the Reactive Streams Specification.
• Swagger — Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification (OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
• Swagger UI — Visualize and interact with the API’s resources.
• Swagger Spring Functional — A friendly Kotlin library used to validate Spring Functional API endpoints against a Swagger 2.0 specification. It leverages the Atlassian request validator.
• JUnit 5 — JUnit 5 is the next generation of JUnit. The goal is to create an up-to-date foundation for developer-side testing on the JVM. This includes focusing on Java 8 and above, as well as enabling many different styles of testing.
• JUnit Jupyter — JUnit Jupiter is the combination of the new programming model and extension model for writing tests and extensions in JUnit 5.
• Gradle — Gradle helps teams build, automate, and deliver better software, faster.

Okay, let’s get started. Here’s how to use the template:

Clone the GitHub project:

git clone https://github.com/cdimascio/kotlin-swagger-spring-functional-template

Build it:

./gradlew build

Execute the tests:

./gradlew test

Run it (locally):

./gradlew run

Try it:

Navigate to http://localhost:8080/

As you can see, getting started with the template is fairly straightforward. Similarly, the template keeps validation simple. The following demonstrates the code required to validate a POST operation’s request body:

UserHandler.kt

fun create(req: ServerRequest) = validate
    .request(req)
    .withBody(User::class.java) { user ->
        ok().body(Mono.just(user))
}

And, with the Spring 5 Kotlin DSL, implementing routing logic is a breeze.

Router.kt

"/api".nest {
    accept(APPLICATION_JSON).nest {
        POST("/users", userHandler::create)
    }
}

Notice that neither the router nor the handler code contains any validation logic. This is because validation is handled declaratively. The template project reads the Open API (Swagger) specification JSON and enforces it.

Below is a snippet from the specification JSON. Notice that it defines firstname and lastname as required properties on the User POST body.

"definitions": {
    "User": {
        "required": [
            "firstname",
            "lastname"
        ],
        "properties": {
            "firstname": {
                "type": "string"
            },
            "lastname": {
                "type": "string"
            }
        }
    }
}

This validation logic is then enforced automatically by swagger-spring-functional (also included in the template project). swagger-spring-functional is configured as follows:

val validate = Validate.configure("static/api.json") { status, messages ->
    // optionally specify a custom error object
    Error(status.value(), messages)
}

Finally, the template project uses Swagger UI to provide beautiful, interactive API documentation. The doc is always kept in sync with the validation logic as both reference the same specification JSON.

To conclude, kotlin-swagger-spring-functional-template makes it easy to get started with Kotlin, Spring 5, and Swagger. It handles the basics for you and provides automatic request validation, interactive API docs, and more. It bootstraps your project, so you don’t have to, letting you focus on what matters most — your code.