Swagger/OpenAPI Generierung auf Kotlin: Werkzeuge und Beispiele

Swagger/OpenAPI Generierung für Kotlin: Von der Spezifikation zum fertigen Code

\n\n

Die Entwicklung moderner APIs erfordert eine klare Dokumentation und eine schnelle Generierung von Client- und Server-Code. Swagger/OpenAPI ist ein Standard zur Beschreibung von RESTful-Schnittstellen, der es ermöglicht, automatisch Code in Kotlin zu erstellen und den Entwickler so von der Routinearbeit des Schreibens von DTOs, Controllern und Clients zu befreien. In diesem Artikel werden wir die wichtigsten Werkzeuge, Konfigurationsbeispiele und praktische Anwendungsszenarien durchgehen.

\n\n

Was ist OpenAPI und warum braucht ein Kotlin-Entwickler es?

\n\n

OpenAPI (früher Swagger) ist eine Spezifikation im YAML- oder JSON-Format, die Endpunkte, Datenmodelle, Anfrage- und Antwortparameter beschreibt. Für Kotlin bietet die Codegenerierung aus OpenAPI:

\n

\n
• Automatisierung — Erstellung von data-Klassen, Enums, Controller-Interfaces
\n
• Konsistenz — Code entspricht immer der Dokumentation
\n
• Zeitersparnis — keine manuelle Serialisierung/Deserialisierung nötig
\n
• Framework-Unterstützung — Ktor, Spring Boot, Retrofit, Micronaut
\n

\n\n

Wichtigste Generierungswerkzeuge

\n\n

Für Kotlin gibt es mehrere ausgereifte Lösungen:

\n\n

1. OpenAPI Generator (offizieller Generator)

\n

Das beliebteste Werkzeug. Unterstützt Dutzende von Sprachen und Frameworks. Für Kotlin sind folgende Generatoren verfügbar:

\n

\n
• kotlin-client — Client auf Basis von Ktor oder Retrofit
\n
• kotlin-server — Server auf Basis von Ktor oder Spring
\n
• kotlin-spring — Spring Boot Controller
\n

\n\n

2. Ktor OpenAPI Plugin

\n

Ein Plugin für das Ktor-Framework, das OpenAPI-Dokumentation aus Code generiert (umgekehrter Ansatz).

\n\n

3. Swagger Codegen (Legacy)

\n

Der Vorgänger des OpenAPI Generators, wird immer noch verwendet, aber es wird empfohlen, auf die neue Version zu migrieren.

\n\n

Beispiel: Generierung eines Kotlin-Clients aus einer OpenAPI-Spezifikation

\n\n

Betrachten wir ein praktisches Beispiel. Angenommen, wir haben eine Datei petstore.yaml (die Standard-Petstore-Spezifikation). Wir generieren einen Kotlin-Client mit dem OpenAPI Generator.

\n\n

Schritt 1: Installation des OpenAPI Generators

\n

Über Homebrew (macOS/Linux):

\n

brew install openapi-generator

\n

Oder über Docker:

\n

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

\n\n

Schritt 2: Konfiguration der Generierung

\n

Erstellen wir eine Konfigurationsdatei config.json:

\n

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

\n\n

Schritt 3: Start der Generierung

\n

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

\n\n

Ergebnis: Generierter Code

\n

Im Ordner generated-client erscheinen:

\n

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

\n\n

Beispiel eines generierten DTOs:

\n

@Serializable\ndata class Pet(\n    val id: Long? = null,\n    @SerialName("category")\n    val category: Category? = null,\n    @SerialName("name")\n    val name: String,\n    @SerialName("photoUrls")\n    val photoUrls: List<String>,\n    val tags: List<Tag>? = null,\n    val status: PetStatus? = null\n)\n\n@Serializable\nenum class PetStatus {\n    @SerialName("available")\n    Available,\n    @SerialName("pending")\n    Pending,\n    @SerialName("sold")\n    Sold\n}

\n\n

Beispiel eines generierten API-Clients (Ktor):

\n

class PetApi(private val client: HttpClient) {\n\n    suspend fun addPet(pet: Pet): Pet = cli