openapi-typescript para TypeScript: guia completo com exemplos

No desenvolvimento web moderno, as interfaces de API desempenham um papel fundamental, e sua especificação através do padrão OpenAPI (anteriormente Swagger) tornou-se o padrão de facto. No entanto, manter manualmente os tipos TypeScript em conformidade com a especificação OpenAPI é um processo trabalhoso e propenso a erros. A biblioteca openapi-typescript resolve esse problema gerando automaticamente tipos TypeScript rigorosos com base no seu esquema OpenAPI (v3.0 e v3.1).

O principal objetivo da biblioteca é garantir uma interação type-safe com a API. Em vez de declarar manualmente interfaces para cada endpoint, você executa o gerador, que cria um arquivo único (ou vários) com tipos para todas as requisições, respostas, parâmetros e esquemas. Isso não apenas economiza tempo, mas também garante que seus tipos estejam sempre sincronizados com a versão atual da API. Se a especificação mudar, basta regenerar os tipos, e o compilador TypeScript apontará imediatamente todas as inconsistências no código.

A biblioteca é amplamente utilizada em projetos onde a confiabilidade e a velocidade de desenvolvimento são críticas: desde arquiteturas de microsserviços até aplicações SPA. Ela suporta a geração tanto para o lado do cliente (por exemplo, para fetch ou axios) quanto para o lado do servidor (por exemplo, para Express ou Fastify). Neste artigo, vamos detalhar a instalação, os principais métodos, exemplos reais e erros comuns.

Instalação

Para instalar a biblioteca, use npm ou yarn. O comando instalará tanto o gerador quanto as dependências necessárias.

npm install openapi-typescript typescript @types/node --save-dev

Ou via yarn:

yarn add -D openapi-typescript typescript @types/node

Se você planeja usar os tipos gerados em tempo de execução (por exemplo, para validação), instale também o openapi-typescript-helpers:

npm install openapi-typescript-helpers

Início rápido — exemplo mínimo funcional

Suponha que você tenha um arquivo spec.yaml com uma especificação OpenAPI. Vamos criar um script simples para gerar os tipos.

// generate.ts
import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

async function main() {
  const spec = fs.readFileSync('./spec.yaml', 'utf-8');
  const result = await createClient(spec, { format: 'yaml' });
  fs.writeFileSync('./api-types.d.ts', result);
  console.log('Tipos gerados em api-types.d.ts');
}

main().catch(console.error);

Execute o script:

npx ts-node generate.ts

Após isso, o arquivo api-types.d.ts conterá todos os tipos correspondentes à sua especificação. Agora você pode importá-los no seu projeto:

import type { paths, components } from './api-types';

// Usando o tipo para um endpoint específico
type GetUsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Principais métodos e funções

1. createClient(schema: string, options?: ClientOptions): Promise<string>

O que faz: Método principal para gerar tipos. Recebe uma string com a especificação (JSON ou YAML) e retorna uma string com o código TypeScript.

import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

const spec = fs.readFileSync('./spec.json', 'utf-8');
const types = await createClient(spec, { format: 'json' });
fs.writeFileSync('./types.d.ts', types);

2. createClientFromUrl(url: string, options?: ClientOptions): Promise<string>

O que faz: Carrega a especificação de forma assíncrona a partir de uma URL e gera os tipos. Útil para APIs remotas.

import { createClientFromUrl } from 'openapi-typescript';

const types = await createClientFromUrl('https://api.exemplo.com/openapi.json');
console.log(types); // Código TypeScript gerado