A microservice example based on Vert.x, Kotlin and OpenAPI 3

This is an example for building a microservice with a technology stack consisting of

• kotlin
• vertx with couroutines and RxJava
• OpenApi3
• JDK 11

Requirements

Requires a JDK 11 or newer due to the usage of the http2 protocol and ALPN.

Furthermore, you need a NASA api key. You can apply for one at their website.

Before you start

Setup the environment as follows:

1. copy .env.txt to .env

   > cp .env.txt .env && chmod 755 .env

2. in .env, set the values for JAVA_HOME and NASA_API_KEY. JAVA_HOME must point to your local installation of a JDK 11.

export JAVA_HOME="/PATH/TO_JDK_v11_HOME"
export NASA_API_KEY="YOUR_NASA_API_KEY"

Building

The pom.xml contains a default maven goal that you can use if you have a java executable of version 11 in your path. So all you have to do is

> mvn 

Alternatively, you can configure a path to a JDK 11 installation in the .env file. That setting will be used by the file test-compile.sh:

> ./test-compile.sh 

Running from the IDE

1. Configure a run configuration in your favorite IDE. Configure it to supply the environment variables from .env to the applycation.
2. Run the main() function from the file main.kt.

Running from the CLI with the enclosed script

> ./run.sh

API

After the pplication started, visit one of the local addresses

• swagger ui instance http 1.1
• swagger ui instance http 2

The application exposes a REST API for rating apod images:

You can learn more about an apod

> curl http://localhost:8080/apod/0

{
  "id": "0",
  "dateString": "2018-07-01",
  "title": "Fresh Tiger Stripes on Saturn's Enceladus",
  "imageUriHd": "https://apod.nasa.gov/apod/image/1807/enceladusstripes_cassini_3237.jpg"
}

You can get the current rating of an apod:

> curl http://localhost:8081/apod/0/rating 

{
  "id": 0,
  "rating": 8
}

Finally you can rate an apod

> curl -X PUT "https://localhost:8443/apod/0/rating" \
       -H "accept: application/json" \ 
       -H "Content-Type: application/json" \
       -d "{\"rating\":9}"

Further Reading

• A good introduction on Kotlin coroutines.
• Official Kotlin docu.
• About Kotlin web API contracts.
• About Kotlin coroutines.