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 provides interactive 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.

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.