Geração Swagger/OpenAPI em Kotlin: guia completo de ferramentas

Geração Swagger/OpenAPI para Kotlin: guia completo

O desenvolvimento de APIs REST modernas exige automação de tarefas rotineiras. Uma das abordagens mais eficazes é a geração de código com base em especificações OpenAPI (anteriormente Swagger). Neste artigo, veremos detalhadamente como usar as ferramentas de geração Swagger/OpenAPI para a linguagem Kotlin, quais bibliotecas estão disponíveis e como aplicá-las corretamente.

O que é Swagger/OpenAPI e por que é necessário para um desenvolvedor Kotlin?

OpenAPI é um padrão para descrever APIs REST nos formatos YAML ou JSON. Ele permite:

• Gerar automaticamente código cliente para aplicativos Android
• Criar stubs e controladores do lado do servidor
• Manter a documentação atualizada
• Acelerar o desenvolvimento em equipes onde backend e frontend trabalham em paralelo

Para Kotlin, que é amplamente utilizado tanto para desenvolvimento de servidores (Ktor, Spring Boot) quanto para aplicativos móveis (Android), a geração de código a partir do OpenAPI torna-se uma ferramenta indispensável.

Principais ferramentas de geração para Kotlin

1. OpenAPI Generator (gerador oficial)

A ferramenta mais popular é o OpenAPI Generator. Ele suporta várias linguagens e frameworks, incluindo Kotlin.

Instalação 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. Geração de cliente para Spring Boot

Se o seu servidor for escrito em Spring Boot, você pode gerar um cliente 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. Geração para Ktor

Ktor é um framework assíncrono moderno para Kotlin. O OpenAPI Generator também o suporta:

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

Exemplo prático: da especificação ao código

Vamos considerar um exemplo simples. Suponha que temos uma especificação 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

Após a geração, obteremos:

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

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

Configurações avançadas e personalização

Uso de templates Mustache personalizados

O OpenAPI Generator usa templates Mustache. Você pode sobrescrevê-los:

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