Swagger/OpenAPI Generation in Kotlin: Tools and Examples

Swagger/OpenAPI Generation for Kotlin: From Specification to Ready Code

Modern API development requires clear documentation and fast generation of client and server code. Swagger/OpenAPI is a standard for describing RESTful interfaces that allows automatic code generation in Kotlin, freeing developers from the routine of writing DTOs, controllers, and clients. In this article, we will cover the main tools, configuration examples, and practical usage scenarios.

What is OpenAPI and Why Does a Kotlin Developer Need It?

OpenAPI (formerly Swagger) is a specification in YAML or JSON format that describes endpoints, data models, request and response parameters. For Kotlin, code generation from OpenAPI provides:

• Automation — creation of data classes, enums, controller interfaces
• Consistency — code always matches the documentation
• Time savings — no need to manually write serialization/deserialization
• Framework support — Ktor, Spring Boot, Retrofit, Micronaut

Main Generation Tools

Several mature solutions exist for Kotlin:

1. OpenAPI Generator (official generator)

The most popular tool. Supports dozens of languages and frameworks. For Kotlin, the following generators are available:

• kotlin-client — client based on Ktor or Retrofit
• kotlin-server — server based on Ktor or Spring
• kotlin-spring — Spring Boot controllers

2. Ktor OpenAPI plugin

A plugin for the Ktor framework that generates OpenAPI documentation from code (reverse approach).

3. Swagger Codegen (legacy)

The predecessor of OpenAPI Generator, still in use, but migration to the new version is recommended.

Example: Generating a Kotlin Client from an OpenAPI Specification

Let's look at a practical example. Suppose we have a file petstore.yaml (the standard Petstore specification). We will generate a Kotlin client using OpenAPI Generator.

Step 1. Install OpenAPI Generator

Via Homebrew (macOS/Linux):

brew install openapi-generator

Or via Docker:

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \  -i /local/petstore.yaml \  -g kotlin-client \  -o /local/out/kotlin-client

Step 2. Configure Generation

Create a configuration file config.json:

{  "packageName": "com.pythonlib.petstore.client",  "library": "ktor",  "serializationLibrary": "kotlinx_serialization",  "useCoroutines": true}

Step 3. Run Generation

openapi-generator generate \  -i petstore.yaml \  -g kotlin-client \  -o ./generated-client \  -c config.json

Result: Generated Code

In the generated-client folder, you will find:

• src/main/kotlin/com/pythonlib/petstore/client/models/Pet.kt
• src/main/kotlin/com/pythonlib/petstore/client/api/PetApi.kt

Example of a generated DTO:

@Serializabledata class Pet(    val id: Long? = null,    @SerialName("category")    val category: Category? = null,    @SerialName("name")    val name: String,    @SerialName("photoUrls")    val photoUrls: List<String>,    val tags: List<Tag>? = null,    val status: PetStatus? = null)

@Serializableenum class PetStatus {    @SerialName("available")    Available,    @SerialName("pending")    Pending,    @SerialName("sold")    Sold}

Example of a generated API client (Ktor):

class PetApi(private val client: HttpClient) {

    suspend fun addPet(pet: Pet): Pet = cli