Swagger/OpenAPI генерация на Kotlin: инструменты и примеры

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

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

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

OpenAPI (ранее Swagger) — это спецификация в формате YAML или JSON, описывающая эндпоинты, модели данных, параметры запросов и ответов. Для Kotlin генерация кода из OpenAPI даёт:

• Автоматизацию — создание классов data, enum, интерфейсов контроллеров
• Согласованность — код всегда соответствует документации
• Экономию времени — не нужно вручную писать сериализацию/десериализацию
• Поддержку фреймворков — Ktor, Spring Boot, Retrofit, Micronaut

Основные инструменты генерации

Для Kotlin существует несколько зрелых решений:

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

Самый популярный инструмент. Поддерживает десятки языков и фреймворков. Для Kotlin доступны генераторы:

• kotlin-client — клиент на Ktor или Retrofit
• kotlin-server — сервер на Ktor или Spring
• kotlin-spring — Spring Boot контроллеры

2. Ktor OpenAPI plugin

Плагин для фреймворка Ktor, который генерирует OpenAPI документацию из кода (обратный подход).

3. Swagger Codegen (легаси)

Предшественник OpenAPI Generator, всё ещё используется, но рекомендуется мигрировать на новую версию.

Пример: генерация Kotlin-клиента из OpenAPI спецификации

Рассмотрим практический пример. Допустим, у нас есть файл petstore.yaml (стандартная Petstore спецификация). Сгенерируем Kotlin-клиент с помощью OpenAPI Generator.

Шаг 1. Установка OpenAPI Generator

Через Homebrew (macOS/Linux):

brew install openapi-generator

Или через Docker:

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

Шаг 2. Настройка генерации

Создадим конфигурационный файл config.json:

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

Шаг 3. Запуск генерации

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

Результат: сгенерированный код

В папке generated-client появятся:

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

Пример сгенерированного DTO:

@Serializable
data 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
)

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

Пример сгенерированного API-клиента (Ktor):

class PetApi(private val client: HttpClient) {

    suspend fun addPet(pet: Pet): Pet = client.post {
        url("http://petstore.swagger.io/v2/pet")
        contentType(ContentType.Application.Json)
        setBody(pet)
    }.body()

    suspend fun getPetById(petId: Long): Pet = client.get {
        url("http://petstore.swagger.io/v2/pet/$petId")
    }.body()

    suspend fun deletePet(petId: Long, apiKey: String? = null): Unit = client.delete {
        url("http://petstore.swagger.io/v2/pet/$petId")
        apiKey?.let { header("