Primeiros passos

O codegen-openapi lê uma spec OpenAPI e escreve o código que o seu frontend precisa para conversar com essa API:

	nextjs	nextjs-pages	react
Route handlers (proxy no servidor para o backend)	✅ route.ts	✅ pages/api/*.ts	—
Services tipados (um por tag OpenAPI)	✅	✅	✅
Hooks React	—	—	✅
apiClient.ts (instância Axios do navegador)	✅	✅	✅
fetchBackend.ts (helper HTTP do servidor)	✅	✅	—

Instalação

npm install --save-dev codegen-openapi

O CLI não tem dependências em runtime. O código gerado importa algumas bibliotecas, que você instala no seu app — o generate confere o seu package.json e mostra o comando exato para instalar o que estiver faltando:

Pacote	Quando é necessário
axios	sempre (usado pelo apiClient.ts e pelo fetchBackend.ts)
js-cookie	quando cookieName está definido
server-only	framework é nextjs ou nextjs-pages
@tanstack/react-query	framework: 'react' com hooksMode: 'react-query' (padrão)

# Next.js
npm install axios server-only js-cookie

# React + React Query
npm install axios js-cookie @tanstack/react-query

TIP

A spec precisa ser OpenAPI 3.0 ou 3.1, em JSON — ou YAML, com o pacote yaml instalado no seu projeto. Swagger 2.0 não é suportado.

Início rápido

Rode o assistente interativo na raiz do projeto:

npx openapi-gen run

Em português ou inglês, ele detecta o framework, carrega a spec para conferir, sugere cada valor, mostra uma revisão do que será gerado, salva o openapi-gen.config.mjs, gera tudo e oferece instalar os pacotes que o código precisa. Digite ? em qualquer pergunta para ver a ajuda.

Adicione um script para que todo o time gere do mesmo jeito:

{
  "scripts": {
    "codegen": "openapi-gen generate"
  }
}

Fluxo do dia a dia

npx openapi-gen diff       # o que mudou na spec em relação aos arquivos em disco
npx openapi-gen generate   # gera tudo de novo (--prune remove endpoints apagados, --watch fica rodando)
npx openapi-gen add        # conecta outra API ao mesmo projeto
npx openapi-gen info       # onde ficam os arquivos e quais variáveis de ambiente definir

Os arquivos gerados são sobrescritos

Todo arquivo começa com // Auto-generated by codegen-openapi — do not edit manually. Coloque sua lógica em arquivos separados que importam os services e hooks gerados.

Usando o código gerado

Next.js — chame o service tipado a partir de um client component; ele acessa o route handler gerado, que faz o proxy para o backend:

'use client';
import usersService from '@/services/users';

const users = await usersService.list({ page: 1 });

React — use os hooks gerados:

import { useList, useCreate } from './hooks/users';

function Users() {
  const { data, isLoading } = useList({ page: 1 });
  const create = useCreate();
  // create.mutate({ body: { name: 'Ana' } })
}

Próximo passo: veja os Comandos e a referência de Configuração.