Comandos

Comando	O que faz
run	Configuração interativa — comece por aqui (English / Português)
add	Conecta outra API
generate	Gera tudo — o comando padrão (--prune, --watch)
diff	O que mudaria, sem escrever nada
info	O que o seu config significa: pastas, variáveis de ambiente, quantidades
init	Cria um config inicial comentado

Todo comando aceita --config <caminho>; por padrão é usado o openapi-gen.config.{mjs,js,ts,mts}. --version e --help funcionam em qualquer lugar.

run

npx openapi-gen run
npx openapi-gen run --lang pt

O assistente faz poucas perguntas, um passo de cada vez:

1. Idioma — English ou Português (o padrão é o idioma do sistema; pule com --lang en|pt)
2. Framework — detectado pelo package.json e pelas pastas
3. Biblioteca de hooks — só React
4. Spec OpenAPI — carregada na hora: você vê o nome da API e o número de endpoints, ou um erro claro como "esta é a página do Swagger UI, use /api-json"
5. Nome da API — sugerido a partir do título da spec
6. URL do backend — a variável de ambiente e um fallback tirado dos servers da spec
7. Autenticação — o cookie de login, ou nada

As escolhas são numeradas — digite 1, 2… ou pressione Enter para a sugestão. Digite ? em qualquer pergunta para ver uma explicação daquele passo com exemplos.

Antes de escrever qualquer coisa ele mostra uma revisão: o arquivo de config, o que será gerado (rotas, services, hooks e onde) e as variáveis para colocar no seu .env. Dá para salvar e gerar, só salvar, ou cancelar. Depois de gerar, ele oferece instalar os pacotes que o código gerado precisa e conectar outra API.

Se já existir um config, o run oferece adicionar uma API a ele ou começar do zero.

Para scripts e CI, o --yes aceita todas as sugestões:

npx openapi-gen run --yes --spec ./openapi.json

add

npx openapi-gen add

Pergunta a spec, um nome e a variável da URL do backend, mostra a revisão e adiciona a API ao seu config — como texto, então seus comentários e a formatação são mantidos. A nova API ganha pastas próprias (src/app/api/<nome>, src/services/<nome>) e reaproveita o auth e os helpers compartilhados. Aceita --lang, --yes e --spec como o run.

generate

npx openapi-gen generate
npx openapi-gen generate --prune
npx openapi-gen generate --watch

1. Valida o config — inclusive erros de digitação: unknown option "framwork" — did you mean "framework"?
2. Carrega todas as specs e aplica include / exclude.
3. Planeja todos os arquivos. Se duas APIs fossem escrever o mesmo arquivo, para antes de escrever qualquer coisa.
4. Escreve os helpers, as rotas, os services (com um index.ts que reexporta todos) e os hooks.
5. Avisa sobre arquivos obsoletos — arquivos gerados cujos endpoints saíram da spec. O --prune apaga esses arquivos. Só arquivos que começam com o cabeçalho Auto-generated by codegen-openapi são tocados.
6. Roda os seus comandos de afterGenerate (ex.: Prettier).
7. Confere os pacotes e mostra o comando para instalar o que faltar (npm, pnpm, yarn ou bun).

O --watch gera de novo sempre que o config ou um arquivo local de spec muda; specs remotas são conferidas a cada 10 segundos.

O comando termina com código 1 quando há erros, então pode rodar no CI.

diff

npx openapi-gen diff

Mostra, sem escrever nada, quais arquivos seriam criados e quais arquivos gerados não existem mais na spec.

info

npx openapi-gen info

Explica o que o config significa depois de aplicar os padrões — útil quando algo foi parar num lugar inesperado:

[core] nextjs
  spec            https://api.example.com/api-json
  endpoints       42
  path prefix     /api (left out of file names, kept in backend calls)
  backend URL     API_URL  (fallback: https://api.example.com)
  routes          18 → src/app/api/
  services        6 → src/services/
  auth            cookie accessToken → Authorization: Bearer

.env
  API_URL=https://api.example.com

init

npx openapi-gen init

Cria um config inicial comentado usando as pastas do seu projeto, sem perguntar nada. O run costuma ser mais rápido porque preenche os valores para você.