Swagger/OpenAPI Generation in Kotlin: A Complete Guide to Tools

Swagger/OpenAPI Generation for Kotlin: A Complete Guide

Developing modern REST APIs requires automating routine tasks. One of the most effective approaches is code generation based on OpenAPI specifications (formerly Swagger). In this article, we will take a detailed look at how to use Swagger/OpenAPI generation tools for the Kotlin language, what libraries are available, and how to use them correctly.

What is Swagger/OpenAPI and why does a Kotlin developer need it?

OpenAPI is a standard for describing REST APIs in YAML or JSON format. It allows you to:

• Automatically generate client code for Android applications
• Create server stubs and controllers
• Keep documentation up to date
• Speed up development in teams where backend and frontend work in parallel

For Kotlin, which is actively used both for server-side development (Ktor, Spring Boot) and mobile applications (Android), code generation from OpenAPI becomes an indispensable tool.

Main Generation Tools for Kotlin

1. OpenAPI Generator (official generator)

The most popular tool is OpenAPI Generator. It supports many languages and frameworks, including Kotlin.

Installation via Gradle:

plugins {    id("org.openapi.generator") version "7.2.0"}

openApiGenerate {    generatorName.set("kotlin")    inputSpec.set("$rootDir/src/main/resources/openapi.yaml")    outputDir.set("$buildDir/generated")    packageName.set("com.example.api")    configOptions.set(mapOf(        "dateLibrary" to "kotlinx-datetime",        "useCoroutines" to "true"    ))}

2. Client Generation for Spring Boot

If your server is written in Spring Boot, you can generate a Kotlin client:

openApiGenerate {    generatorName.set("kotlin-spring")    inputSpec.set("${projectDir}/api-spec.yaml")    outputDir.set("${buildDir}/generated")    apiPackage.set("com.example.api")    modelPackage.set("com.example.model")    configOptions.set(mapOf(        "library" to "spring-boot",        "useTags" to "true"    ))}

3. Generation for Ktor

Ktor is a modern asynchronous framework for Kotlin. OpenAPI Generator also supports it:

openApiGenerate {    generatorName.set("kotlin-ktor")    inputSpec.set("api.yaml")    outputDir.set("generated")    configOptions.set(mapOf(        "dateLibrary" to "kotlinx-datetime",        "serializationLibrary" to "kotlinx_serialization"    ))}

Workflow Example: From Specification to Code

Let's consider a simple example. Suppose we have a specification pets.yaml:

openapi: "3.0.0"info:  title: Pet Store API  version: "1.0"paths:  /pets:    get:      operationId: listPets      responses:        '200':          description: OK          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/Pet'components:  schemas:    Pet:      type: object      properties:        id:          type: integer        name:          type: string

After generation, we will get:

// Pet.kt (generated data class)data class Pet(    val id: Int,    val name: String)

// PetsApi.kt (generated interface)interface PetsApi {    suspend fun listPets(): List<Pet>}

Advanced Settings and Customization

Using Custom Mustache Templates

OpenAPI Generator uses Mustache templates. You can override them:

openApiGenerate {    templateDir.set("$rootDir/templates/kotlin")    // Add