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 e arquivos de configuração. Você instala sua CLI, aponta para sua especificação, escolhe um gerador como `typescript-axios` ou `spring`, e ele escreve o código em uma pasta de saída. Este guia mostra como instalá-lo, listar os geradores disponíveis e produzir clientes e servidores para várias linguagens.
O que é OpenAPI Generator
OpenAPI Generator lê uma descrição de API legível por máquina e emite código-fonte a partir dela. Dê a ele um arquivo `openapi.yaml` (ou JSON) e ele pode gerar uma biblioteca cliente para chamar essa API, um stub de servidor que a implementa, além de documentação e configuração.
Ele suporta tanto OpenAPI v2 (o formato Swagger mais antigo) quanto OpenAPI v3. O projeto é mantido pela organização OpenAPITools no GitHub, com templates para dezenas de linguagens e frameworks.
A distinção principal: este é um gerador de código, não um gerador de documentação. Ferramentas de documentação como Swagger UI ou Redoc renderizam sua especificação em páginas HTML legíveis por humanos. O OpenAPI Generator, em vez disso, produz código que você compila e distribui. Ele também pode emitir documentos Markdown, mas seu trabalho principal são os SDKs e stubs.
Como se relaciona com Swagger Codegen
Se você já usou Swagger Codegen, OpenAPI Generator parecerá familiar. Ele 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 de seus principais colaboradores e criadores de templates.
A bifurcação ocorreu após um desacordo sobre a direção do Swagger Codegen 3.0.0. A comunidade queria um ciclo de lançamento mais rápido e aberto. As notas oficiais da bifurcação descrevem o projeto como baseado no Swagger Codegen 2.4.0-SNAPSHOT, então os dois compartilham raízes profundas. Se você está avaliando os dois, a análise de alternativas ao Swagger Codegen cobre as diferenças práticas.
Instalando OpenAPI Generator
Você tem quatro caminhos de instalação comuns. Escolha o que melhor se adapta à sua stack.
npm (mais comum)
O wrapper npm é o ponto de entrada mais fácil para a maioria das equipes. Ele baixa e gerencia o JAR subjacente para você.
npm install @openapitools/openapi-generator-cli -g
Você também pode executá-lo sem uma instalação global:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
JAR autônomo
OpenAPI Generator é um aplicativo Java, então você pode baixar o JAR diretamente do Maven Central e executá-lo com Java. Isso evita completamente a camada npm ou Homebrew.
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
Verifique o Maven Central para o número da versão mais recente antes de baixar.
Docker
A imagem oficial permite gerar código sem instalar nada localmente. Monte seu diretório de trabalho no container para que ele possa ler sua especificação e gravar a saída de volta.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Listando os geradores disponíveis
Antes de gerar qualquer coisa, veja quais geradores existem. Cada gerador tem como alvo uma linguagem mais framework, como `java`, `python` ou `spring`.
openapi-generator-cli list
Para uma visualização compacta, uma por linha, use a flag curta e divida por vírgulas:
openapi-generator-cli list -s | tr ',' '\n'
A lista separa geradores de cliente (para chamar uma API) de geradores de servidor (para implementar uma), além de geradores de documentação e esquema.
Gerando um SDK de cliente
O comando principal é `generate`. Ele leva três argumentos que você usará sempre:
-i, --input-specaponta para seu arquivo ou URL de especificação.-g, --generator-nameseleciona qual gerador executar.-o, --outputdefine o diretório de saída.
Aqui está um cliente TypeScript construído em Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Isso escreve um cliente tipado em `./client`. Cada operação em sua especificação se torna um método, e cada esquema se torna um modelo.
O mesmo padrão funciona em várias linguagens. Troque o nome do gerador e a pasta de saída:
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
Como o código vem de uma única especificação, cada cliente permanece consistente com o contrato. Quando a especificação muda, você regenera e seus SDKs a seguem.
Gerando stubs de servidor
Geradores de servidor invertem a direção. Em vez de código que chama sua API, você obtém um andaime que a implementa, com roteamento, modelos de solicitação e interfaces de manipulador configurados. Você preenche a lógica de negócios.
Aqui está um stub de servidor Spring Boot:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
O projeto gerado oferece controladores e DTOs correspondentes à sua especificação. Você implementa os métodos da interface, e as formas de solicitação e resposta já estão definidas para você. Isso mantém o servidor em execução alinhado com o contrato publicado.
Configurando a saída
A saída padrão raramente é exatamente o que você deseja. OpenAPI Generator oferece vários controles.
Propriedades adicionais
A maioria dos geradores expõe opções por linguagem através de `--additional-properties` (alias curto `-p`). Passe-as como pares `chave=valor` delimitados por vírgulas:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Cada gerador documenta suas próprias propriedades, então verifique a página do gerador para a lista completa de chaves que ele aceita.
Um arquivo de configuração
Quando a linha de comando fica longa, mova as opções para um arquivo de configuração. JSON e YAML são suportados.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Um arquivo de configuração mantém suas configurações de geração no controle de versão ao lado da especificação, o que torna as compilações reproduzíveis.
Ignorando arquivos
OpenAPI Generator lê um arquivo `.openapi-generator-ignore` no diretório de saída. Ele usa a mesma sintaxe que `.gitignore`. Use-o para impedir que o gerador sobrescreva arquivos que você editou manualmente.
# .openapi-generator-ignore
*.md
src/custom/**
Você pode apontar para um arquivo de ignorar em outro local com `--ignore-file-override <local>`.
Templates personalizados
Todo gerador é impulsionado por templates Mustache. Se a saída padrão não corresponder ao seu estilo interno, copie os templates, edite-os e passe seu diretório com `-t`:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Esta é a ferramenta certa quando você precisa de um cabeçalho personalizado, um cliente HTTP diferente ou convenções de nomenclatura internas incorporadas em cada arquivo gerado.
Executando em CI
A geração de código pertence ao seu pipeline, não ao laptop de um único desenvolvedor. Regenerar o cliente a cada mudança na especificação para que o SDK commitado nunca se desvie do contrato. Aqui está um passo do GitHub Actions usando `npx`:
- name: Gerar cliente API
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Você pode fazer a compilação falhar se a saída regenerada for diferente do que está commitado, o que detecta especificações e SDKs que se desalinharam.
Mantenha a especificação como sua única fonte de verdade
OpenAPI Generator é tão bom quanto a especificação que você o alimenta. Entra lixo, sai lixo: uma especificação vaga ou inválida produz um SDK vago ou quebrado. Portanto, o passo mais valioso acontece antes mesmo de você executar `generate`. Você torna a especificação correta, completa e estável.
É aqui que o Apidog se encaixa. Apidog é uma plataforma de API tudo-em-um que é nativa de OpenAPI, então seu trabalho de design e sua especificação são o mesmo artefato. Você projeta ou importa a API, e Apidog mantém o documento OpenAPI como a fonte da verdade de onde tudo o mais flui.
Um fluxo de trabalho limpo se parece com isto:
- Projete ou importe a especificação OpenAPI no Apidog. O suporte a branch permite que você trabalhe em mudanças isoladamente, semelhante ao controle de versão OpenAPI com Git.
- Valide e faça lint na especificação antes de gerar. Uma especificação que passa por um linter OpenAPI e um validador Swagger produz um código mais limpo com menos surpresas.
- Exporte a especificação validada e, em seguida, alimente-a no OpenAPI Generator para seus SDKs e stubs.
Você também pode manter a especificação sincronizada com seu repositório, por exemplo, sincronizando a especificação OpenAPI com o GitHub, e revisar as alterações com um diff OpenAPI antes que elas sejam lançadas. Se você está migrando de ferramentas mais antigas, a comparação de alternativas ao Swagger para design e teste de API é um bom ponto de partida.
Onde o Apidog para e o OpenAPI Generator começa
Vale a pena ser preciso aqui. O Apidog não gera SDKs de cliente completos ou stubs de servidor. Esse é o trabalho do OpenAPI Generator, e os dois são complementares em vez de concorrentes.
O Apidog oferece trechos de solicitação de cliente prontos para copiar para cada endpoint, em muitas linguagens e clientes HTTP. São exemplos por solicitação que você pode colar em um script, não uma biblioteca empacotada. Para uma biblioteca gerada e versionada ou um scaffold de servidor, você executa o OpenAPI Generator na especificação que o Apidog produz.
O Apidog também oferece seu próprio test runner de linha de comando, o Apidog CLI, que é separado da geração de código. Ele executa seus testes de API em CI; ele não gera SDKs. Instale e use-o assim:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Você passa a autenticação com `--access-token`, `-t` seleciona o cenário de teste, `-e` escolhe o ambiente para executar e `-r` seleciona os reporters. Execute-o em uma versão LTS atual do Node.js. Para detalhes de configuração, consulte o guia de instalação do Apidog CLI e o passo a passo sobre como testar uma API REST da linha de comando.
Então, o ciclo completo é: projetar e validar a especificação no Apidog, gerar SDKs e stubs com OpenAPI Generator e, em seguida, verificar a API em execução com o 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 produz SDKs de cliente, stubs de servidor, documentação e arquivos de configuração, e suporta tanto OpenAPI v2 quanto v3.
Como você usa OpenAPI Generator?
Instale a CLI (por exemplo, `npm install @openapitools/openapi-generator-cli -g`), depois execute `generate` com três flags: `-i` para sua especificação, `-g` para o gerador e `-o` para a pasta de saída. Execute `openapi-generator-cli list` primeiro para ver todos os geradores disponíveis.
Como funciona o OpenAPI Generator?
Ele analisa sua especificação em um modelo interno, depois renderiza esse modelo através de templates Mustache para o seu alvo escolhido. Cada operação se torna um método ou manipulador, e cada esquema se torna um modelo tipado. Você pode sobrescrever os templates com `-t` para alterar a saída.
Como você gera um SDK de cliente a partir de uma especificação OpenAPI?
Escolha um gerador de cliente e execute `generate`. Por exemplo, `openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client` constrói um cliente TypeScript tipado. Troque `typescript-axios` por `java`, `python` ou `go` para direcionar outras linguagens.
Como você gera stubs de servidor?
Escolha um gerador de servidor. Para um scaffold Spring Boot, execute `openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring`. A saída inclui controladores e modelos de solicitação de sua especificação, e você implementa a lógica do manipulador.
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 de seus colaboradores, que desejavam um ciclo de lançamento mais rápido e impulsionado pela comunidade. Os dois compartilham uma base comum, mas o OpenAPI Generator agora tem seu próprio roadmap, conjunto de geradores e cronograma de lançamento.
Como você gera 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`. Execute `openapi-generator-cli list` para confirmar o nome exato do gerador e ver outras opções de framework PHP antes de gerar.