Swagger/OpenAPI-Generierung in Kotlin: Vollständiger Leitfaden zu den Tools

Swagger/OpenAPI-Generierung für Kotlin: Vollständige Anleitung

Die Entwicklung moderner REST-APIs erfordert die Automatisierung von Routineaufgaben. Einer der effektivsten Ansätze ist die Codegenerierung auf Basis von OpenAPI-Spezifikationen (früher Swagger). In diesem Artikel betrachten wir im Detail, wie man Swagger/OpenAPI-Generierungstools für die Sprache Kotlin verwendet, welche Bibliotheken verfügbar sind und wie man sie richtig einsetzt.

Was ist Swagger/OpenAPI und warum braucht ein Kotlin-Entwickler das?

OpenAPI ist ein Standard zur Beschreibung von REST-APIs im YAML- oder JSON-Format. Es ermöglicht:

• Automatische Generierung von Client-Code für Android-Anwendungen
• Erstellung von Server-Stubs und Controllern
• Aktualität der Dokumentation sicherzustellen
• Beschleunigung der Entwicklung in Teams, in denen Backend und Frontend parallel arbeiten

Für Kotlin, das sowohl für die Serverentwicklung (Ktor, Spring Boot) als auch für mobile Anwendungen (Android) aktiv genutzt wird, wird die Codegenerierung aus OpenAPI zu einem unverzichtbaren Werkzeug.

Wichtigste Generierungstools für Kotlin

1. OpenAPI Generator (offizieller Generator)

Das beliebteste Tool ist der OpenAPI Generator. Er unterstützt viele Sprachen und Frameworks, einschließlich Kotlin.

Installation über 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-Generierung für Spring Boot

Wenn Ihr Server auf Spring Boot basiert, können Sie einen Kotlin-Client generieren:

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. Generierung für Ktor

Ktor ist ein modernes asynchrones Framework für Kotlin. Der OpenAPI Generator unterstützt auch dieses:

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

Beispielablauf: Von der Spezifikation zum Code

Betrachten wir ein einfaches Beispiel. Angenommen, wir haben eine Spezifikation 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

Nach der Generierung erhalten wir:

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

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

Erweiterte Einstellungen und Anpassung

Verwendung eigener Mustache-Vorlagen

Der OpenAPI Generator verwendet Mustache-Vorlagen. Sie können diese überschreiben:

openApiGenerate {    templateDir.set("$rootDir/templates/kotlin")    // Fügen Sie