Construindo Clientes de API Type-Safe com OpenAPI e TypeScript

Todo desenvolvedor frontend já passou por isso: você busca dados de uma API, acessa um campo que deveria existir e recebe undefined em tempo de execução. O TypeScript deveria prevenir isso. O problema é que response.json() retorna any, então o compilador não tem nada para verificar. Este guia mostra como corrigir isso adequadamente—gerando tipos diretamente da sua especificação OpenAPI e usando-os para construir clientes REST type-safe em TypeScript.

Por Que a Tipagem Manual Falha

A correção ingênua é escrever interfaces manualmente:

// ❌ Compila bem, mas o TypeScript está apenas confiando em você
const data = (await response.json()) as User

Isso fornece autocomplete, mas se torna uma mentira no momento em que o backend muda. Seus tipos se desalinham da realidade, e você volta às surpresas em tempo de execução.

A melhor abordagem: gerar tipos a partir da fonte da verdade—sua especificação OpenAPI.

O Fluxo de Trabalho de Geração de Código OpenAPI TypeScript

O fluxo de trabalho típico se parece com isto:

1. Comece com uma especificação OpenAPI (YAML ou JSON, hospedada ou local)
2. Execute um gerador para produzir tipos TypeScript ou um cliente completo
3. Importe esses tipos no código da sua aplicação

Isso mantém seu frontend sincronizado com o backend automaticamente. Quando a especificação muda, você regenera e o TypeScript informa exatamente o que quebrou.

Escolhendo Sua Abordagem: Apenas Tipos vs. SDK de Cliente Completo

Existem duas estratégias principais para geração de código OpenAPI TypeScript, e a escolha certa depende do seu projeto.

Geração apenas de tipos mantém seu bundle pequeno e permite que você controle a camada HTTP. Geração completa de SDK economiza tempo de configuração, mas adiciona mais código gerado para manter.

OpenAPI 3.0 vs 3.1: A maioria das ferramentas suporta bem o OpenAPI 3.0. O suporte ao OpenAPI 3.1 varia—verifique a documentação do seu gerador antes de assumir compatibilidade completa.

Abordagem 1: openapi-typescript com openapi-fetch

Este é o caminho com runtime mínimo. Gere tipos da sua especificação, depois use openapi-fetch como um wrapper fino e totalmente tipado em torno da API Fetch nativa.

npx openapi-typescript ./openapi.yaml -o ./src/api/types.ts
npm install openapi-fetch

import createClient from "openapi-fetch"
import type { paths } from "./api/types"

const client = createClient<paths>({ baseUrl: "https://api.example.com" })

// Path, parâmetros e resposta são todos verificados por tipo
const { data, error } = await client.GET("/users/{id}", {
  params: { path: { id: 123 } },
})

// TypeScript sabe exatamente como `data` se parece
console.log(data?.email)

Erros de digitação em paths, tipos de parâmetros incorretos e formatos de resposta incompatíveis se tornam erros de compilação. Overhead mínimo em runtime e apenas uma pequena dependência de runtime (openapi-fetch).

Abordagem 2: Orval para Geração Completa de Cliente

O Orval gera funções de API tipadas e—criticamente—pode gerar hooks do TanStack Query diretamente da sua especificação. Isso é útil quando você quer que a lógica de busca de dados seja tratada para você.

npm install orval --save-dev

Configure orval.config.ts para apontar para sua especificação e escolha um modo de saída (fetch, axios ou react-query). O Orval então gera funções como useGetUsers() com segurança de tipo completa incorporada.

Esta abordagem adiciona mais código gerado, mas para APIs maiores reduz significativamente o boilerplate.

Mantendo os Tipos Sincronizados

O valor real da geração de cliente OpenAPI TypeScript só se mantém se você regenerar consistentemente. Adicione a etapa de geração ao seu fluxo de trabalho de desenvolvimento:

{
  "scripts": {
    "generate:api": "openapi-typescript ./openapi.yaml -o ./src/api/types.ts"
  }
}

Execute no CI, ou observe mudanças na especificação localmente. Algumas equipes commitam o arquivo gerado; outras regeneram a cada build. Qualquer uma funciona—apenas torne automático.

O Que Você Ainda Precisa Lidar

Tipos gerados geralmente fornecem segurança apenas em tempo de compilação. A validação em tempo de execução requer ferramentas adicionais como Zod ou plugins de gerador. Para endpoints críticos, combine seus tipos gerados com Zod para validar respostas em tempo de execução e capturar bugs do backend antes que eles cheguem à sua UI.

Conclusão

A geração de código OpenAPI TypeScript é uma das melhorias de maior impacto que você pode fazer em uma base de código frontend. Escolha openapi-typescript com openapi-fetch para uma configuração leve, ou Orval se você quiser hooks de query gerados. De qualquer forma, você para de escrever tipos manualmente, para de adivinhar formatos de resposta e deixa o compilador fazer o trabalho para o qual foi projetado.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.