DEV Community

Cover image for OpenAPI Generator: Como Gerar Código de Cliente e Servidor API
Lucas
Lucas

Posted on • Originally published at apidog.com

OpenAPI Generator: Como Gerar Código de Cliente e Servidor API

OpenAPI Generator é uma ferramenta de código aberto que transforma uma especificação OpenAPI ou Swagger em código funcional: SDKs de cliente, stubs de servidor, documentação e arquivos de configuração. Na prática, você instala a CLI, aponta para um openapi.yaml, escolhe um gerador como typescript-axios ou spring e grava a saída em uma pasta do projeto.

Experimente o Apidog hoje

O que é OpenAPI Generator

OpenAPI Generator lê uma descrição de API em formato OpenAPI/Swagger e gera código a partir dela. Com um arquivo openapi.yaml ou openapi.json, você pode gerar:

  • SDKs de cliente para consumir uma API;
  • stubs de servidor para implementar uma API;
  • modelos tipados;
  • documentação;
  • arquivos de configuração e build.

Ele suporta OpenAPI v2, o formato Swagger mais antigo, e OpenAPI v3. O projeto é mantido pela organização OpenAPITools no GitHub e inclui templates para dezenas de linguagens e frameworks.

A diferença principal é esta: OpenAPI Generator é um gerador de código, não apenas uma ferramenta de documentação. Swagger UI e Redoc renderizam a especificação em páginas HTML para leitura humana. OpenAPI Generator produz código que você compila, publica ou usa como base de implementação.

Como se relaciona com Swagger Codegen

OpenAPI Generator foi bifurcado do Swagger Codegen em maio de 2018, entre as versões 2.3.1 e 2.4.0 do Swagger Codegen, por mais de 40 colaboradores e criadores de templates.

A bifurcação ocorreu após desacordos sobre a direção do Swagger Codegen 3.0.0. A comunidade queria um ciclo de lançamento mais rápido e aberto. Os dois projetos compartilham raízes, mas hoje seguem roadmaps e ciclos de release próprios.

Se você está comparando as opções, veja esta análise de alternativas ao Swagger Codegen.

Instalando OpenAPI Generator

Escolha o método que melhor se encaixa no seu ambiente.

npm

O wrapper npm é uma das formas mais simples de usar a CLI. Ele baixa e gerencia o JAR usado internamente.

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

Verifique a instalação:

openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Ou execute sem instalação global:

npx @openapitools/openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Homebrew no macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

Depois valide:

openapi-generator version
Enter fullscreen mode Exit fullscreen mode

JAR autônomo

OpenAPI Generator é uma aplicação Java. Você pode baixar o JAR diretamente do Maven Central e executá-lo com java.

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar

java -jar openapi-generator-cli.jar help
Enter fullscreen mode Exit fullscreen mode

Antes de usar em produção, confira no Maven Central qual é a versão mais recente.

Docker

Use Docker quando não quiser instalar Java, npm ou Homebrew na máquina local.

docker pull openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Gere código montando o diretório atual dentro do container:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml \
  -g go \
  -o /local/out/go
Enter fullscreen mode Exit fullscreen mode

Listando os geradores disponíveis

Antes de gerar código, descubra quais geradores estão disponíveis.

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Para uma saída mais compacta, uma opção por linha:

openapi-generator-cli list -s | tr ',' '\n'
Enter fullscreen mode Exit fullscreen mode

A lista inclui geradores de:

  • clientes, como typescript-axios, java, python, go;
  • servidores, como spring;
  • documentação;
  • esquemas e configurações auxiliares.

Gerando um SDK de cliente

O comando principal é generate.

Você quase sempre usará estas três flags:

  • -i, --input-spec: caminho ou URL da especificação;
  • -g, --generator-name: nome do gerador;
  • -o, --output: diretório de saída.

Exemplo com TypeScript e Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Isso cria um cliente tipado em ./client. Em geral:

  • operações da especificação viram métodos;
  • schemas viram modelos;
  • parâmetros e respostas ficam tipados conforme o contrato OpenAPI.

O mesmo padrão funciona para outras linguagens:

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

Quando a especificação mudar, regenere o SDK:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Esse fluxo mantém os clientes alinhados com o contrato da API.

Gerando stubs de servidor

Geradores de servidor fazem o caminho inverso: em vez de gerar código para chamar a API, eles criam um scaffold para implementá-la.

Exemplo com Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

A saída pode incluir controladores, DTOs, modelos de request/response e interfaces de handler. Você completa a lógica de negócio nos pontos gerados.

Esse fluxo é útil quando você quer começar a implementação pelo contrato OpenAPI e garantir que o servidor siga a especificação publicada.

Configurando a saída

A saída padrão raramente é exatamente o que um projeto real precisa. Use as opções abaixo para ajustar o código gerado.

Usando propriedades adicionais

A maioria dos geradores expõe opções específicas por linguagem via --additional-properties ou -p.

Exemplo:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Enter fullscreen mode Exit fullscreen mode

Use esse recurso para configurar detalhes como:

  • nome do pacote;
  • versão do pacote;
  • organização de modelos e APIs;
  • compatibilidade de linguagem;
  • convenções do gerador escolhido.

Cada gerador tem suas próprias chaves. Antes de automatizar, consulte a documentação do gerador que você está usando.

Usando um arquivo de configuração

Quando o comando começa a ficar longo, mova as opções para um arquivo de configuração.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -c config.yaml
Enter fullscreen mode Exit fullscreen mode

Isso mantém a configuração versionada junto com a especificação e torna a geração reproduzível no ambiente local e em CI.

Ignorando arquivos gerados

OpenAPI Generator lê um arquivo .openapi-generator-ignore no diretório de saída. A sintaxe é semelhante à do .gitignore.

Exemplo:

# .openapi-generator-ignore
*.md
src/custom/**
Enter fullscreen mode Exit fullscreen mode

Use isso para impedir que o gerador sobrescreva arquivos que você edita manualmente.

Também é possível apontar para outro arquivo de ignore:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --ignore-file-override ./generator-ignore
Enter fullscreen mode Exit fullscreen mode

Usando templates personalizados

Os geradores usam templates Mustache. Se a saída padrão não seguir o padrão interno do seu time, personalize os templates.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

Esse caminho faz sentido quando você precisa padronizar:

  • cabeçalhos de arquivos;
  • convenções de nomenclatura;
  • estrutura de diretórios;
  • cliente HTTP;
  • wrappers internos;
  • tratamento de erro.

Executando em CI

A geração de código deve estar no pipeline, não apenas na máquina de um desenvolvedor.

Exemplo de etapa no GitHub Actions usando npx:

- name: Gerar cliente API
  run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Enter fullscreen mode Exit fullscreen mode

Um fluxo comum é:

  1. validar a especificação OpenAPI;
  2. gerar o SDK;
  3. rodar testes/build;
  4. falhar o pipeline se houver diferença entre o código gerado e o código commitado.

Exemplo para detectar mudanças não commitadas:

- name: Verificar mudanças geradas
  run: |
    git diff --exit-code
Enter fullscreen mode Exit fullscreen mode

Assim, se a especificação mudar e o SDK não for atualizado, o CI detecta o desalinhamento.

Mantenha a especificação como sua única fonte de verdade

OpenAPI Generator depende diretamente da qualidade da especificação. Uma especificação vaga, incompleta ou inválida gera um SDK igualmente problemático.

Antes de executar generate, garanta que o contrato esteja correto:

  • schemas completos;
  • parâmetros bem definidos;
  • códigos de resposta esperados;
  • exemplos quando úteis;
  • autenticação documentada;
  • nomes consistentes de operações e modelos.

É aqui que o Apidog se encaixa. Apidog é uma plataforma de API nativa de OpenAPI: você projeta ou importa a API e mantém o documento OpenAPI como fonte da verdade.

Um fluxo prático:

  1. Projete ou importe a especificação OpenAPI no Apidog. O suporte a branch permite trabalhar em mudanças isoladas, semelhante ao controle de versão OpenAPI com Git.
  2. Valide e faça lint da especificação antes de gerar código. Uma especificação aprovada por um linter OpenAPI e por um validador Swagger tende a gerar clientes mais previsíveis.
  3. Exporte a especificação validada.
  4. Use essa especificação como entrada do OpenAPI Generator.
  5. Publique ou versione os SDKs e stubs gerados.

Você também pode manter a especificação sincronizada com o repositório, por exemplo sincronizando a especificação OpenAPI com o GitHub, e revisar mudanças com um diff OpenAPI antes do release.

Se você está migrando de ferramentas mais antigas, a comparação de alternativas ao Swagger para design e teste de API pode ajudar.

Onde o Apidog para e o OpenAPI Generator começa

Vale ser preciso: o Apidog não gera SDKs completos de cliente nem stubs completos de servidor. Esse é o papel do OpenAPI Generator.

As ferramentas são complementares:

  • Apidog ajuda a projetar, validar, testar e manter a especificação OpenAPI;
  • OpenAPI Generator transforma essa especificação em SDKs, stubs e outros artefatos;
  • Apidog CLI executa testes de API em linha de comando e CI.

O Apidog também oferece trechos de solicitação prontos para copiar em vários clientes HTTP e linguagens. Esses snippets são exemplos por endpoint, não uma biblioteca versionada completa.

Para uma biblioteca empacotada ou um scaffold de servidor, gere com OpenAPI Generator a partir da especificação exportada.

Executando testes com Apidog CLI

O Apidog CLI é separado da geração de código. Ele executa testes de API em CI.

Instalação:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

Execução:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <testScenarioId> \
  -e <envId> \
  -r cli,html \
  -n 1
Enter fullscreen mode Exit fullscreen mode

Parâmetros principais:

  • --access-token: token de autenticação;
  • -t: cenário de teste;
  • -e: ambiente;
  • -r: reporters;
  • -n: número de iterações.

Use uma versão LTS atual do Node.js. Para mais detalhes, consulte o guia de instalação do Apidog CLI e o tutorial sobre como testar uma API REST da linha de comando.

O ciclo completo fica assim:

  1. projete e valide a especificação no Apidog;
  2. gere SDKs e stubs com OpenAPI Generator;
  3. execute testes da API em CI com Apidog CLI.

Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito.

Perguntas Frequentes

O que é OpenAPI Generator?

OpenAPI Generator é uma ferramenta de código aberto da organização OpenAPITools que gera código a partir de uma especificação OpenAPI ou Swagger. Ele pode produzir SDKs de cliente, stubs de servidor, documentação e arquivos de configuração. Suporta OpenAPI v2 e v3.

Como usar OpenAPI Generator?

Instale a CLI e execute generate com as flags principais:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Antes disso, use list para ver os geradores disponíveis:

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Como o OpenAPI Generator funciona?

Ele analisa a especificação OpenAPI, transforma o contrato em um modelo interno e renderiza esse modelo por meio de templates Mustache. Operações viram métodos ou handlers, e schemas viram modelos tipados.

Você pode sobrescrever templates com -t:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

Como gerar um SDK de cliente a partir de uma especificação OpenAPI?

Escolha um gerador de cliente e execute generate.

Exemplo com TypeScript e Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Para outras linguagens, troque o gerador:

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

Como gerar stubs de servidor?

Escolha um gerador de servidor. Para Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

A saída inclui a estrutura inicial do servidor. Você implementa a lógica de negócio nos handlers ou controladores gerados.

Qual é a diferença entre OpenAPI Generator e Swagger Codegen?

OpenAPI Generator foi bifurcado do Swagger Codegen em maio de 2018 por mais de 40 colaboradores que queriam um ciclo de release mais rápido e orientado pela comunidade. Os projetos compartilham uma base histórica, mas hoje têm roadmaps, geradores e cronogramas próprios.

Como gerar um SDK PHP a partir de uma especificação OpenAPI?

Use o gerador php:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g php \
  -o ./client-php
Enter fullscreen mode Exit fullscreen mode

Para confirmar o nome exato do gerador e verificar opções relacionadas a PHP, execute:

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Top comments (0)