Geração Swagger/OpenAPI em Kotlin: ferramentas e exemplos

Geração Swagger/OpenAPI para Kotlin: da especificação ao código pronto

O desenvolvimento de APIs modernas exige documentação clara e geração rápida de código cliente e servidor. Swagger/OpenAPI é o padrão para descrição de interfaces RESTful que permite criar automaticamente código em Kotlin, livrando o desenvolvedor da tarefa rotineira de escrever DTOs, controladores e clientes. Neste artigo, abordaremos as principais ferramentas, exemplos de configuração e cenários práticos de uso.

O que é OpenAPI e por que é importante para o desenvolvedor Kotlin?

OpenAPI (anteriormente Swagger) é uma especificação em formato YAML ou JSON que descreve endpoints, modelos de dados, parâmetros de requisição e respostas. Para Kotlin, a geração de código a partir do OpenAPI oferece:

• Automação — criação de classes data, enum, interfaces de controladores
• Consistência — o código sempre corresponde à documentação
• Economia de tempo — não é necessário escrever serialização/desserialização manualmente
• Suporte a frameworks — Ktor, Spring Boot, Retrofit, Micronaut

Principais ferramentas de geração

Para Kotlin, existem várias soluções maduras:

1. OpenAPI Generator (gerador oficial)

A ferramenta mais popular. Suporta dezenas de linguagens e frameworks. Para Kotlin, estão disponíveis os geradores:

• kotlin-client — cliente em Ktor ou Retrofit
• kotlin-server — servidor em Ktor ou Spring
• kotlin-spring — controladores Spring Boot

2. Plugin Ktor OpenAPI

Plugin para o framework Ktor que gera documentação OpenAPI a partir do código (abordagem inversa).

3. Swagger Codegen (legado)

Predecessor do OpenAPI Generator, ainda em uso, mas recomenda-se migrar para a nova versão.

Exemplo: geração de cliente Kotlin a partir de especificação OpenAPI

Vamos considerar um exemplo prático. Suponha que temos um arquivo petstore.yaml (especificação Petstore padrão). Geraremos um cliente Kotlin usando o OpenAPI Generator.

Passo 1. Instalação do OpenAPI Generator

Via Homebrew (macOS/Linux):

brew install openapi-generator

Ou via Docker:

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

Passo 2. Configuração da geração

Criaremos um arquivo de configuração config.json:

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

Passo 3. Execução da geração

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

Resultado: código gerado

Na pasta generated-client aparecerão:

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

Exemplo de DTO gerado:

@Serializabledata class Pet(    val id: Long? = null,    @SerialName("category")    val category: Category? = null,    @SerialName("name")    val name: String,    @SerialName("photoUrls")    val photoUrls: List<String>,    val tags: List<Tag>? = null,    val status: PetStatus? = null)

@Serializableenum class PetStatus {    @SerialName("available")    Available,    @SerialName("pending")    Pending,    @SerialName("sold")    Sold}

Exemplo de cliente API gerado (Ktor):

class PetApi(private val client: HttpClient) {

    suspend fun addPet(pet: Pet): Pet = cli