Tipagem automática com OpenAPI

• Segurança em tempo de compilação: o TypeScript avisa caso você envie parâmetros errados ou tente acessar campos inexistentes na resposta.

• Produtividade: você escreve menos boilerplate — o código repetitivo de integração.

• Sincronia: toda vez que o back-end mudar, basta atualizar a especificação OpenAPI e regenerar o cliente front-end.

• Autocompletar e intellisense: a IDE sugere rotas, parâmetros e respostas possíveis.

Conhecendo as ferramentas: um arsenal para dominar as APIs

1. OpenAPI TypeScript

npx openapi-typescript ./openapi.json -o ./src/api.ts

// Exemplo fictício de tipagens que podem ser geradas
export interface paths {
  '/users': {
    get: {
      responses: {
        200: {
          content: {
            'application/json': User[];
          };
        };
      };
    };
  };
  // ...
}

export interface User {
  id: string;
  name: string;
  email: string;
}

import { useQuery } from 'react-query';
import { paths } from './api';

function fetchUsers(): Promise<paths['/users']['get']['responses']['200']['content']['application/json']> {
  return fetch('https://api.meuservidor.com/users').then(res => res.json());
}

export function UserList() {
  const { data, isLoading } = useQuery('users', fetchUsers);

  if (isLoading) return <div>Carregando...</div>;

  return (
    <ul>
      {data?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

• Simples e fácil de instalar.

• Gera tipagens fortes.

• Menos intuitivo para quem quer geração completa (requisições, hooks, etc.).

• Normalmente requer configuração adicional para uso em grandes projetos.

2. Hey API

// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  schema: './openapi.json',
  output: {
    path: './src/http/generated',
  },
  plugins: [
    {
      name: 'react-query', // Gera hooks de React Query
    },
    // Outros plugins (mocks, etc.)
  ],
});

• Services: funções puras para requisição (fetch).

• Hooks de React Query.

• Arquivos de Tipos (para interfaces e enums).

import { useQuery } from 'react-query';
import { getGetUsersOptions } from './http/generated'; // Opções geradas

export function UserList() {
  const { data, isLoading } = useQuery({
    ...getGetUsersOptions(), // Chama a função gerada automaticamente
  });

  if (isLoading) {
    return <div>Carregando...</div>;
  }

  return (
    <ul>
      {data?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

• Extensível (arquitetura de plugins).

• Integração nativa com React Query.

• Geração de mocks para testes.

• Projeto mais recente, menos robusto do que Orval.

• Comunidade menor (até o momento).

3. Orval

// orval.config.js
module.exports = {
  exemplo: {
    output: {
      mode: 'split',
      target: './src/api/generated.ts',
      schemas: './src/api/model',
      client: 'react-query',
    },
    input: {
      target: './openapi.json',
    },
  },
};

// Exemplo no componente React
import { useGetUsers, useCreateUser } from './api/generated';

function UserList() {
  const { data: users, isLoading } = useGetUsers();
  const mutation = useCreateUser();

  if (isLoading) return <div>Carregando...</div>;

  const handleCreateUser = (newUserData: any) => {
    mutation.mutate({ data: newUserData });
  };

  return (
    <div>
      {users?.map(u => (
        <li key={u.id}>{u.name}</li>
      ))}
      {/* Formulário de criação */}
    </div>
  );
}

• Maduro, com boa comunidade e mais estável.

• Altamente customizável.

• Integração com vários frameworks além de React.

• Ainda não exporta os tipos de erro do back-end de forma nativa (principal dor de cabeça para quem quer lidar com erros de forma robusta).

4. Kubb

// kubb.config.ts
import { defineConfig } from '@kubb/core';
import swagger from '@kubb/swagger';
import swaggerTs from '@kubb/swagger-ts';
import swaggerTanstackQuery from '@kubb/swagger-tanstack-query';
import swaggerZod from '@kubb/swagger-zod';

export default defineConfig(() => {
  return {
    input: {
      path: './openapi.json',
    },
    output: {
      path: './src/gen',
      clean: true,
    },
    plugins: [
      swagger({ output: false }),
      swaggerTs({ output: { path: 'models' } }),
      swaggerTanstackQuery({
        output: { path: 'react-query' },
        client: {
          importPath: '../client.ts', // Cliente customizado
        },
      }),
      swaggerZod({ output: { path: 'zod' } }),
    ],
  };
});

// client.ts
export async function customFetch<TData, TError>(
  url: string,
  options: RequestInit
): Promise<[TError | null, TData | null]> {
  const response = await fetch(url, options);

  if (!response.ok) {
    // Lidar com erro retornado pela API
    const errorData = (await response.json()) as TError;
    return [errorData, null];
  }

  const data = (await response.json()) as TData;
  return [null, data];
}

import { useGetUsers } from './gen/react-query';

export function UserList() {
  const { data, isLoading } = useGetUsers();
  // data é: [error, users] | undefined

  if (isLoading) return <div>Carregando...</div>;

  const [error, users] = data ?? [null, null];

  if (error) {
    return <div>Erro: {error.message}</div>;
  }

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

• Altamente customizável, permitindo separar tudo em plugins.

• Integração com Zod, SWR, React Query, Vue, Svelte, etc.

• Pode gerar tipagem de erros bem detalhada, conforme a especificação OpenAPI.

• É muito novo, sujeito a mudanças.

• Comunidade ainda pequena, exigindo cautela em projetos grandes.

Lidando com erros de forma inteligente: o poder das tuplas

// Exemplo hipotético de verificação de erro
const [error, data] = await createUserMutation.mutateAsync({ data: userInfo });

if (error) {
  // error é tipado de acordo com o que a API pode retornar
  console.error(error);
  return alert(`Erro: ${error.message}`);
}

// data não é nulo aqui, porque se chegou até esse ponto, deu certo
console.log(`Usuário criado: ${data.name}`);

Material extra para se aprofundar

• OpenAPI (Swagger): https://swagger.io/specification/

• OpenAPI TypeScript: https://www.npmjs.com/package/openapi-typescript

• HEY API: https://heyapi.dev/

• Orval: https://orval.dev/

• Kubb: https://kubb.dev/

• OpenAPI Generator: https://openapi-generator.tech/

Conclusão: o futuro do consumo de APIs é tipado e automatizado