Generación de Swagger/OpenAPI en Kotlin: herramientas y ejemplos

Generación de Swagger/OpenAPI para Kotlin: de la especificación al código listo

El desarrollo de APIs modernas requiere documentación clara y generación rápida de código de cliente y servidor. Swagger/OpenAPI es el estándar para describir interfaces RESTful que permite crear automáticamente código en Kotlin, liberando al desarrollador de la tediosa escritura de DTOs, controladores y clientes. En este artículo analizaremos las principales herramientas, ejemplos de configuración y casos de uso prácticos.

¿Qué es OpenAPI y por qué es útil para un desarrollador Kotlin?

OpenAPI (anteriormente Swagger) es una especificación en formato YAML o JSON que describe endpoints, modelos de datos, parámetros de solicitudes y respuestas. Para Kotlin, la generación de código a partir de OpenAPI proporciona:

• Automatización — creación de clases data, enum, interfaces de controladores
• Consistencia — el código siempre coincide con la documentación
• Ahorro de tiempo — no es necesario escribir manualmente la serialización/deserialización
• Soporte de frameworks — Ktor, Spring Boot, Retrofit, Micronaut

Principales herramientas de generación

Para Kotlin existen varias soluciones maduras:

1. OpenAPI Generator (generador oficial)

La herramienta más popular. Soporta decenas de lenguajes y frameworks. Para Kotlin están disponibles los generadores:

• kotlin-client — cliente en Ktor o Retrofit
• kotlin-server — servidor en Ktor o Spring
• kotlin-spring — controladores Spring Boot

2. Plugin Ktor OpenAPI

Plugin para el framework Ktor que genera documentación OpenAPI a partir del código (enfoque inverso).

3. Swagger Codegen (legado)

Predecesor de OpenAPI Generator, todavía se usa, pero se recomienda migrar a la nueva versión.

Ejemplo: generación de un cliente Kotlin a partir de una especificación OpenAPI

Veamos un ejemplo práctico. Supongamos que tenemos un archivo petstore.yaml (especificación estándar de Petstore). Generaremos un cliente Kotlin usando OpenAPI Generator.

Paso 1. Instalación de OpenAPI Generator

Mediante Homebrew (macOS/Linux):

brew install openapi-generator

O mediante Docker:

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

Paso 2. Configuración de la generación

Creemos un archivo de configuración config.json:

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

Paso 3. Ejecutar la generación

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

Resultado: código generado

En la carpeta generated-client aparecerán:

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

Ejemplo de DTO generado:

@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}

Ejemplo de API cliente generado (Ktor):

class PetApi(private val client: HttpClient) {

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