Génération Swagger/OpenAPI sur Kotlin : outils et exemples

Génération Swagger/OpenAPI pour Kotlin : de la spécification au code prêt à l'emploi

\n\n

Le développement d'API modernes nécessite une documentation claire et une génération rapide de code client et serveur. Swagger/OpenAPI est un standard de description d'interfaces RESTful qui permet de créer automatiquement du code en Kotlin, libérant le développeur de l'écriture fastidieuse des DTO, contrôleurs et clients. Dans cet article, nous analyserons les principaux outils, des exemples de configuration et des scénarios pratiques d'utilisation.

\n\n

Qu'est-ce qu'OpenAPI et pourquoi est-ce utile pour un développeur Kotlin ?

\n\n

OpenAPI (anciennement Swagger) est une spécification au format YAML ou JSON décrivant les endpoints, les modèles de données, les paramètres de requêtes et de réponses. Pour Kotlin, la génération de code à partir d'OpenAPI offre :

\n

\n
• Automatisation — création de classes data, enum, interfaces de contrôleurs
\n
• Cohérence — le code correspond toujours à la documentation
\n
• Gain de temps — plus besoin d'écrire manuellement la sérialisation/désérialisation
\n
• Support des frameworks — Ktor, Spring Boot, Retrofit, Micronaut
\n

\n\n

Principaux outils de génération

\n\n

Pour Kotlin, il existe plusieurs solutions matures :

\n\n

1. OpenAPI Generator (générateur officiel)

\n

L'outil le plus populaire. Il prend en charge des dizaines de langages et frameworks. Pour Kotlin, les générateurs disponibles sont :

\n

\n
• kotlin-client — client sur Ktor ou Retrofit
\n
• kotlin-server — serveur sur Ktor ou Spring
\n
• kotlin-spring — contrôleurs Spring Boot
\n

\n\n

2. Plugin Ktor OpenAPI

\n

Plugin pour le framework Ktor qui génère la documentation OpenAPI à partir du code (approche inverse).

\n\n

3. Swagger Codegen (legacy)

\n

Prédécesseur d'OpenAPI Generator, encore utilisé, mais il est recommandé de migrer vers la nouvelle version.

\n\n

Exemple : génération d'un client Kotlin à partir d'une spécification OpenAPI

\n\n

Prenons un exemple pratique. Supposons que nous ayons un fichier petstore.yaml (spécification Petstore standard). Générons un client Kotlin avec OpenAPI Generator.

\n\n

Étape 1. Installation d'OpenAPI Generator

\n

Avec Homebrew (macOS/Linux) :

\n

brew install openapi-generator

\n

Ou avec 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

Étape 2. Configuration de la génération

\n

Créons un fichier de configuration config.json :

\n

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

\n\n

Étape 3. Lancement de la génération

\n

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

\n\n

Résultat : code généré

\n

Dans le dossier generated-client, vous trouverez :

\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

Exemple de DTO généré :

\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

Exemple de client API généré (Ktor) :

\n

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