API-first development with Quarkus and Kotlin

API-first and code-first development with OpenAPI

Using OpenAPI specifications is not limited to API-first development. OpenAPI specifications can also be used in a process that is usually called code-first development. Many web development frameworks offer options to directly generate the OpenAPI specification from the implemented endpoints, thereby making the specification a byproduct of the implementation. To end up with usable specifications, this approach often requires enhancing the endpoint implementations with additional documentation or annotations to guide the OpenAPI generation process. My personal feeling is that it is pretty hard to end up with a specification that is of similar value and rigor as a hand-crafted one. Moreover, the required annotations often make the endpoint implementation more verbose and harder to read. See Required annotations for good OpenAPI specifications in Spring Boot for an example of how this might pollute an otherwise simple implementation. In contrast, Endpoint definition in an OpenAPI specification shows a comparable endpoint definition specified using OpenAPI. The specification is better readable and avoids polluting the implementation. In any case, if you decide against going the API-first approach, generated specification are often better than having nothing at all. However, you will also lose most of the aforementioned benefits of the general API-first process.

@Operation(summary = "Get a book by its id")
@ApiResponses(value = {
  @ApiResponse(responseCode = "200", description = "Found the book",
    content = { @Content(mediaType = "application/json",
      schema = @Schema(implementation = Book.class)) }),
  @ApiResponse(responseCode = "400", description = "Invalid id supplied",
    content = @Content),
  @ApiResponse(responseCode = "404", description = "Book not found",
    content = @Content) })
@GetMapping("/{id}")
public Book findById(@Parameter(description = "id of book to be searched")
  @PathVariable long id) {
    return repository.findById(id).orElseThrow(() -> new BookNotFoundException());
}

paths:
  /books/{book_id}:
    get:
      summary: Get a book by its id
      parameters:
        - $ref: "#/components/parameters/BookId"
      responses:
        "200":
          description: Found the book
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
        "400":
          description: Invalid id supplied
        "404":
          description: Book not found

Add the API definition to the project

The first step we need to do is to provide the API definition file in the project resources so that we can bootstrap the API-first workflow from the specification in that file. For this purpose, the petstore.yaml file mentioned before is placed under src/main/resources/META-INF/openapi.yaml. This is the canonical path for a pre-defined OpenAPI specification for some of the Quarkus extensions used later on. Other locations would be possible but would require further configuration options.

Enable SwaggerUI

When working with an OpenAPI specification, one usually wants to provide a SwaggerUI based on the API specification for easier development and experimentation with the implemented API. Quarkus can natively serve the SwaggerUI using an extension, which we add to the dependencies section in pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

With these changes in place, we can start the Quarkus project for the first time using:

$ ./mvnw quarkus:dev

Afterwards, the new SwaggerUI is available as part of the Quarkus Dev UI under http://localhost:8080/q/dev-ui/io.quarkus.quarkus-smallrye-openapi/swagger-ui.

Only serve the defined API in SwaggerUI

By default, SwaggerUI would serve a combined specification comprising the contents of the YAML file and further endpoints declared only in the application code. In an API-first world, this is usually not desired, because any publicly available endpoint has to be defined in the OpenAPI specification first before being implement. To avoid this behavior, we restrict SwaggerUI to only serve the statically defined specification by adding the following line to src/main/resources/application.properties:

mp.openapi.scan.disable=true

Let Quarkus determine the server in the OpenAPI specification

The OpenAPI standard allows defining servers, which are URLs under which the API is served for clients. These servers are selectable in SwaggerUI and used when testing requests there. This model is nice for testing publicly deployed APIS. However, it doesn’t work well for local development purposes. We’d have to anticipate all potential local testing environment of different developer systems and pollute the servers array with all of them (IPv4 vs IPv6, running on a remote test host vs. localhost, etc.) so that local testing is possible. To prevent this configuration issue, it is better to let Quarkus determine a suitable server for us depending on how the application is launched and accessed.

The first thing we need to do is to get rid of any manually defined servers in the servers array of openapi.yaml:

servers: []

The second thing to do is to instruct Quarkus to add a suitable server automatically by adding another option to src/main/resources/application.properties:

quarkus.smallrye-openapi.auto-add-server=true

Afterwards, we get an auto-generated server that’s suitable for local development:

Generate API stubs using the OpenAPI Generator

One of the main benefits of an API-first approach with an OpenAPI specification is that we can make use of the OpenAPI Generator to generate code from the specification. This ensures that our implementation complies to the implementation and does not drift from it over time. And it also avoids manual work for us. Therefore, the next thing we do is to use the OpenAPI Generator Maven plugin to generate REST resource interfaces and model classes for use. Afterwards, actually providing the endpoints boils down to implementing the generated interfaces using the generate model classes.

Setting up the OpenAPI Generator plugin is a bit involved and I’ll explain the different configuration options in detail after showing the full plugin configuration, which needs to be added to the plugins section in pom.xml:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.7.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/META-INF/openapi.yaml</inputSpec> 1
                <generatorName>kotlin-server</generatorName> 2
                <modelPackage>${project.groupId}.adapters.rest</modelPackage> 3
                <apiPackage>${project.groupId}.adapters.rest</apiPackage> 3
                <generateApiTests>false</generateApiTests> 4
                <generateModelTests>false</generateModelTests> 4
                <generateSupportingFiles>false</generateSupportingFiles> 5
                <configOptions>
                    <sourceFolder>src/main/kotlin</sourceFolder>
                    <library>jaxrs-spec</library> 6
                    <useJakartaEe>true</useJakartaEe> 6
                    <interfaceOnly>true</interfaceOnly> 7
                    <useCoroutines>true</useCoroutines> 8
                    <returnResponse>true</returnResponse> 9
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

With this configuration in place, a fresh run of ./mvnw compile (or ./mvnw generate-sources) results in the OpenAPI Generator creating two classes. First, a model class for a Pet complying with the defined JSON format when serialized:

package de.semipol.adapters.rest

import com.fasterxml.jackson.annotation.JsonProperty

data class Pet (
    @JsonProperty("id")
    val id: kotlin.Long,

    @JsonProperty("name")
    val name: kotlin.String,

    @JsonProperty("tag")
    val tag: kotlin.String? = null
)

Second, an interface for a REST resource providing the routes defined in the API specification:

package de.semipol.adapters.rest;

import de.semipol.adapters.rest.Error
import de.semipol.adapters.rest.Pet
import jakarta.ws.rs.*
import jakarta.ws.rs.core.Response
import java.io.InputStream

@Path("/")
@jakarta.annotation.Generated(value = arrayOf("org.openapitools.codegen.languages.KotlinServerCodegen"), comments = "Generator version: 7.7.0")
interface PetsApi {

    @POST
    @Path("/pets")
    @Consumes("application/json")
    @Produces("application/json")
    suspend fun createPets( pet: Pet): Response

    @GET
    @Path("/pets")
    @Produces("application/json")
    suspend fun listPets(@QueryParam("limit")   limit: kotlin.Int?): Response

    @GET
    @Path("/pets/{petId}")
    @Produces("application/json")
    suspend fun showPetById(@PathParam("petId") petId: kotlin.String): Response
}

We can now go along and implement this interface using a separate class.

Implementing a generated API resource

Implementing the API boils down to creating a class that implements the generated PetsApi interface. Before I can show how this looks like, we first need a dummy backend to store and request instances of Pet from. Here’s a simple stub repository implementation [Fowler2003] for pets that’s used in the example project:

@ApplicationScoped
class PetRepository {
    private val pets = mutableListOf<Pet>()

    fun clear() {
        pets.clear()
    }

    fun addPet(pet: Pet) {
        pets.add(pet)
    }

    fun listPets(): List<Pet> = pets

    fun getPet(id: Long): Pet = pets.first { it.id == id }
}

With this repository in place, we can now implement the REST API:

class PetsApiImpl(private val petRepository: PetRepository) : PetsApi { 1

    @ServerExceptionMapper 3
    public fun mapNoSuchElementException(e: NoSuchElementException) =
        Response
            .status(Status.NOT_FOUND)
            .entity(Error(Status.NOT_FOUND.statusCode, e.message ?: ""))
            .build()

    override suspend fun createPets(pet: Pet): Response {
        petRepository.addPet(pet)
        return Response.created(URI.create("/pets/${pet.id}")).build()
    }

    override suspend fun listPets(limit: Int?): Response {
        return Response.ok(petRepository.listPets()).header("x-next", "fake value").build() 2
    }

    override suspend fun showPetById(petId: Long): Response {
        return Response.ok(petRepository.getPet(petId)).build()
    }
}

The resulting implementation is pretty concise and easy to read. The generated interface ensures that the implementation provides the required routes with matching input parameters. Iterating the specification is easy and free from loss of manually implemented code. When the OpenAPI specification is modified, the manually implemented endpoints remain untouched and the compiler will spot the most severe discrepancies that need to be addressed. For instance, if a new route is added, we cannot forget to implement it, because otherwise the interface is not implemented correctly. This gives a lot of automated support for ensuring consistent and complete API implementations, complying with the specification.