Generación de Swagger/OpenAPI en Kotlin: guía completa de herramientas

Generación de Swagger/OpenAPI para Kotlin: guía completa

El desarrollo de API REST modernas requiere la automatización de tareas rutinarias. Uno de los enfoques más efectivos es la generación de código basada en especificaciones OpenAPI (anteriormente Swagger). En este artículo, veremos en detalle cómo usar las herramientas de generación de Swagger/OpenAPI para el lenguaje Kotlin, qué bibliotecas están disponibles y cómo aplicarlas correctamente.

¿Qué es Swagger/OpenAPI y por qué lo necesita un desarrollador de Kotlin?

OpenAPI es un estándar para describir API REST en formato YAML o JSON. Permite:

• Generar automáticamente código de cliente para aplicaciones Android
• Crear stubs y controladores del lado del servidor
• Mantener la documentación actualizada
• Acelerar el desarrollo en equipos donde backend y frontend trabajan en paralelo

Para Kotlin, que se utiliza activamente tanto para el desarrollo del lado del servidor (Ktor, Spring Boot) como para aplicaciones móviles (Android), la generación de código a partir de OpenAPI se convierte en una herramienta indispensable.

Principales herramientas de generación para Kotlin

1. OpenAPI Generator (generador oficial)

La herramienta más popular es OpenAPI Generator. Soporta muchos lenguajes y frameworks, incluido Kotlin.

Instalación a través de 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. Generación de cliente para Spring Boot

Si su servidor está escrito en Spring Boot, puede generar un cliente Kotlin:

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. Generación para Ktor

Ktor es un framework asíncrono moderno para Kotlin. OpenAPI Generator también lo soporta:

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

Ejemplo de trabajo: de la especificación al código

Consideremos un ejemplo simple. Supongamos que tenemos una especificación 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

Después de la generación obtendremos:

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

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

Configuración avanzada y personalización

Uso de plantillas Mustache personalizadas

OpenAPI Generator utiliza plantillas Mustache. Puede sobrescribirlas:

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