Geração Swagger/OpenAPI para TypeScript: bibliotecas e ferramentas

Geração Swagger/OpenAPI para TypeScript: automatização da criação de clientes API

Ao desenvolver aplicações web modernas em TypeScript, surge frequentemente a necessidade de integrar com uma REST API descrita através de especificações OpenAPI (anteriormente conhecidas como Swagger). Escrever manualmente tipos, interfaces e código cliente não só consome muito tempo, mas também é propenso a erros, especialmente quando o backend sofre alterações. Ferramentas de geração automática de código TypeScript a partir de especificações OpenAPI vêm em nosso auxílio. Neste artigo, analisaremos três soluções mais populares: openapi-typescript, orval e swagger-typescript-api, além de comparar suas funcionalidades.

Por que a geração de TypeScript a partir de OpenAPI é necessária?

O objetivo principal é sincronizar tipos e código cliente entre o frontend e o backend. Vantagens da geração automática:

• Segurança de tipos: Todos os endpoints, parâmetros de requisição e respostas recebem tipos TypeScript estritos.
• Atualidade: Ao alterar a especificação, basta regenerar o código, sem necessidade de edições manuais.
• Aceleração do desenvolvimento: O desenvolvedor obtém funções prontas para chamar a API com autocompletar (IntelliSense).
• Minimização de erros: Eliminam-se erros de digitação em nomes de campos e incompatibilidades de tipos.

openapi-typescript

A biblioteca openapi-typescript (dos criadores do openapi-fetch) é um gerador de tipos leve. Ela cria apenas interfaces e tipos TypeScript, sem gerar código cliente para chamadas de API. É a escolha ideal para projetos onde é necessário tipar dados estritamente, mas a forma de chamar a API fica a critério do desenvolvedor (por exemplo, via fetch ou axios).

Instalação:

npm install -D openapi-typescript

Exemplo de uso (gerando tipos a partir do arquivo spec.yaml):

npx openapi-typescript ./spec.yaml -o ./types/api.ts

O resultado é um arquivo com tipos que podem ser importados:

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

// Tipo para a resposta de GET /userstype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Prós: Minimalismo, geração rápida, excelente suporte para schemas complexos (allOf, oneOf).
Contras: Não possui funções prontas para chamar a API, exigindo um wrapper adicional.

orval

Orval é um poderoso gerador que cria não apenas tipos, mas também hooks React totalmente funcionais, bem como clientes para axios, fetch ou Angular. É particularmente útil em projetos React que utilizam React Query (TanStack Query).

Instalação:

npm install -D orval

Configuração no arquivo orval.config.ts:

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // ou 'axios', 'fetch', 'angular'    },  },};

Executando a geração:

npx orval

Exemplo de hook gerado:

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // data será tipado automaticamente}

Prós: Integração pronta com React Query, suporte a mutações, gerenciamento automático de cache.
Contras: Grande volume de código gerado, dependência de um cliente HTTP específico.

swagger-typescript-api

A biblioteca swagger-typescript-api oferece geração flexível: é possível obter tanto tipos simples quanto um cliente API completo com suporte a vários clientes HTTP (axios, fetch). Uma característica distintiva é a possibilidade de personalizar os templates de geração.

Instalação: