Pare de escrever integrações no braço

Integrar APIs no front-end costuma ser um trabalho repetitivo: criar types/DTOs, escrever clients HTTP, montar hooks, tratar loading/erro e manter tudo atualizado quando o backend muda.

Hoje, com uma API bem documentada em OpenAPI (Swagger), dá para automatizar quase tudo isso.

A ideia é simples: se o contrato da API já existe e está bem descrito, o front-end não precisa “recriar” o contrato no braço. Ele pode gerar código a partir dele.

É aí que entra o Orval.

O que é Orval

Orval é uma ferramenta que consome uma especificação OpenAPI e gera código TypeScript pronto para uso no front-end, incluindo:

Types (schemas, responses, params)
Clients (fetch/axios)
Hooks (React Query ou SWR, dependendo do setup)
Organização por domínios/tags

Com isso, o OpenAPI vira a fonte de verdade: o contrato muda → você roda o gerador → o front se atualiza.

Pré-requisito: OpenAPI bem definido

O Orval precisa de um OpenAPI, que pode ser:

Um arquivo local: openapi.yaml / openapi.json
Uma URL: https://api.suaempresa.com/openapi.json

Quanto melhor o contrato (schemas claros, responses corretos, operationId consistente), melhor a qualidade do código gerado.

Instalação

npm install -D orval

Configuração básica

Crie um arquivo orval.config.ts na raiz do projeto:

export default {
  api: {
    input: {
      target: "https://api.exemplo.com/openapi.json",
    },
    output: {
      mode: "split",
      client: "axios",
      target: "./src/api/endpoints",
      schemas: "./src/api/model",
    },
  },
};

Rode o gerador:

npx orval

Nesse ponto, você já terá types e funções de acesso aos endpoints gerados.

Gerando hooks com React Query

Para gerar hooks automaticamente (queries e mutations), habilite o override.query:

export default {
  api: {
    input: {
      target: "https://api.exemplo.com/openapi.json",
    },
    output: {
      mode: "split",
      client: "axios",
      target: "./src/api/endpoints",
      schemas: "./src/api/model",
      override: {
        query: {
          useQuery: true,
          useMutation: true,
          signal: true,
        },
      },
    },
  },
};

Rode novamente:

npx orval

Agora o Orval passa a gerar hooks como useGetUser, useCreateUser, etc. (os nomes variam conforme operationId/tags da sua spec).

Centralizando HTTP (baseURL, auth, interceptors)

Em projetos reais, você quer controlar autenticação, baseURL e interceptors. Para isso, use um mutator.

Crie ./src/api/http.ts:

import axios from "axios";

export const http = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
});

http.interceptors.request.use((config) => {
  const token = typeof window !== "undefined" ? localStorage.getItem("token") : null;
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

Aponte o mutator no Orval:

export default {
  api: {
    input: {
      target: "https://api.exemplo.com/openapi.json",
    },
    output: {
      mode: "split",
      client: "axios",
      target: "./src/api/endpoints",
      schemas: "./src/api/model",
      override: {
        mutator: {
          path: "./src/api/http.ts",
          name: "http",
        },
        query: {
          useQuery: true,
          useMutation: true,
          signal: true,
        },
      },
    },
  },
};

Rode:

npx orval

Com isso, tudo que for gerado vai usar sua instância http.

Uso no React

Exemplo de consumo de um hook gerado:

import { useGetUser } from "@/api/endpoints/users";

export function UserProfile({ id }: { id: string }) {
  const { data, isLoading, error } = useGetUser(id);

  if (isLoading) return <p>Carregando...</p>;
  if (error) return <p>Erro ao carregar usuário</p>;

  return (
    <div>
      <h2>{data?.name}</h2>
      <p>{data?.email}</p>
    </div>
  );
}

O ponto é: você não precisou escrever manualmente types, client e hook. Você só usa.

Script no package.json

Para padronizar o fluxo do time:

{
  "scripts": {
    "api:generate": "orval"
  }
}

Uso:

npm run api:generate

Fluxo recomendado no time

Um fluxo simples que funciona muito bem:

Backend atualiza/publica o OpenAPI
Front roda npm run api:generate
PR inclui o diff do código gerado
App fica alinhado ao contrato sem esforço manual

Isso reduz:

retrabalho de integração
divergência de tipagem
bugs de contrato
tempo gasto “traduzindo” API para o front

E aumenta:

velocidade de entrega
consistência
confiança nas integrações

Conclusão

Se você já tem (ou pode ter) uma API bem documentada em OpenAPI, não faz sentido continuar criando types e hooks no braço.

Com Orval, a integração vira um processo automático: contrato bem definido → código gerado → foco no produto.

A economia de tempo é real e escala junto com a sua API.