Swagger/OpenAPI генерация в Kotlin: полный гайд по инструментам

Swagger/OpenAPI генерация для Kotlin: полное руководство

Разработка современных REST API требует автоматизации рутинных задач. Одним из самых эффективных подходов является генерация кода на основе спецификаций OpenAPI (ранее Swagger). В этой статье мы подробно рассмотрим, как использовать инструменты генерации Swagger/OpenAPI для языка Kotlin, какие библиотеки доступны и как их правильно применять.

Что такое Swagger/OpenAPI и зачем это нужно Kotlin-разработчику?

OpenAPI — это стандарт описания REST API в формате YAML или JSON. Он позволяет:

• Автоматически генерировать клиентский код для Android-приложений
• Создавать серверные заглушки и контроллеры
• Поддерживать документацию в актуальном состоянии
• Ускорять разработку в командах, где бэкенд и фронтенд работают параллельно

Для Kotlin, который активно используется как для серверной разработки (Ktor, Spring Boot), так и для мобильных приложений (Android), генерация кода из OpenAPI становится незаменимым инструментом.

Основные инструменты генерации для Kotlin

1. OpenAPI Generator (официальный генератор)

Самый популярный инструмент — OpenAPI Generator. Он поддерживает множество языков и фреймворков, включая Kotlin.

Установка через 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. Генерация клиента для Spring Boot

Если ваш сервер написан на Spring Boot, вы можете сгенерировать 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. Генерация для Ktor

Ktor — современный асинхронный фреймворк для Kotlin. OpenAPI Generator поддерживает и его:

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

Пример работы: от спецификации к коду

Рассмотрим простой пример. Допустим, у нас есть спецификация 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

После генерации мы получим:

// Pet.kt (сгенерированный data class)
data class Pet(
    val id: Int,
    val name: String
)

// PetsApi.kt (сгенерированный интерфейс)
interface PetsApi {
    suspend fun listPets(): List<Pet>
}

Продвинутые настройки и кастомизация

Использование собственных шаблонов Mustache

OpenAPI Generator использует шаблоны Mustache. Вы можете переопределить их:

openApiGenerate {
    templateDir.set("$rootDir/templates/kotlin")
    // Добавьте свои шаблоны в папку templates/kotlin
}

Настройка сериализации

Для Kotlin важно правильно настроить сериализацию. Рекомендуется использовать kotlinx.serialization:

configOptions.set(mapOf(
    "serializationLibrary" to "kotlinx_serialization",
    "serializableModel" to "true"
))

Интеграция с Gradle Build Cache

Чтобы избежать повторной генерации при каждой сборке:

tasks.withType<org.openapitools.generator.gradle.plugin.tasks.GenerateTask>() {
    outputs.cacheIf { true }
}

Лучшие практики

• Версионируйте спецификации — храните OpenAPI-файлы