Génération Swagger/OpenAPI en Kotlin : guide complet des outils

Génération Swagger/OpenAPI pour Kotlin : guide complet

Le développement d'API REST modernes nécessite l'automatisation des tâches répétitives. L'une des approches les plus efficaces est la génération de code basée sur les spécifications OpenAPI (anciennement Swagger). Dans cet article, nous examinerons en détail comment utiliser les outils de génération Swagger/OpenAPI pour le langage Kotlin, quelles bibliothèques sont disponibles et comment les utiliser correctement.

Qu'est-ce que Swagger/OpenAPI et pourquoi en avez-vous besoin en tant que développeur Kotlin ?

OpenAPI est un standard de description d'API REST au format YAML ou JSON. Il permet de :

• Générer automatiquement du code client pour les applications Android
• Créer des stubs serveur et des contrôleurs
• Maintenir la documentation à jour
• Accélérer le développement dans les équipes où le backend et le frontend travaillent en parallèle

Pour Kotlin, qui est activement utilisé à la fois pour le développement serveur (Ktor, Spring Boot) et pour les applications mobiles (Android), la génération de code à partir d'OpenAPI devient un outil indispensable.

Principaux outils de génération pour Kotlin

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

L'outil le plus populaire est OpenAPI Generator. Il prend en charge de nombreux langages et frameworks, y compris Kotlin.

Installation via 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. Génération de client pour Spring Boot

Si votre serveur est écrit avec Spring Boot, vous pouvez générer un client 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. Génération pour Ktor

Ktor est un framework asynchrone moderne pour Kotlin. OpenAPI Generator le prend également en charge :

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

Exemple de travail : de la spécification au code

Prenons un exemple simple. Supposons que nous ayons une spécification 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

Après la génération, nous obtiendrons :

// Pet.kt (data class généré)data class Pet(    val id: Int,    val name: String)

// PetsApi.kt (interface générée)interface PetsApi {    suspend fun listPets(): List<Pet>}

Paramètres avancés et personnalisation

Utilisation de modèles Mustache personnalisés

OpenAPI Generator utilise des modèles Mustache. Vous pouvez les remplacer :

openApiGenerate {    templateDir.set("$rootDir/templates/kotlin")    // Ajoutez