Pare de escrever suas requisições http!!!
Muitas vezes, ao desenvolver apliações que consomem APIs, nos deparamos com o desafio de escrever requisições HTTP para interagir com o backend. Isso envolve a criação de URLs, manipulação de cabeçalhos, envio de parâmetros e tratamento de respostas. Esse processo pode ser tedioso e propenso a erros, principalmente quando o backend realiza modificações em suas rotas ou estrutura de dados sem comunicar adequadamente o frontend. A falta de alinhamento entre as duas partes pode levar a erros, falhas e experiências desagradáveis para os usuários.
Mas existe uma solução para simplificar esse processo e torná-lo mais robusto. Essa solução envolve o uso de padrões de design que automatizam a geração de código para requisições HTTP. Isso não apenas economiza tempo, mas também ajuda a evitar erros comuns, garantindo que o frontend esteja sempre em sincronia com o backend, mesmo quando ocorrem alterações.
🚨 Atenção 🚨
É importante observar que, se você está no início de sua jornada de aprendizado sobre padrões de design e princípios SOLID, NÃO PULE ESSAS ETAPAS. Entender esses conceitos é fundamental para se tornar um desenvolvedor mais competente e eficaz. No entanto, mesmo se você estiver nesse processo de aprendizado, pode continuar lendo o post que oferece uma solução prática para elevar seu nível de conhecimento e melhorar sua eficiência.
Sem rinha de frontend 🚫
No final do post deixei o link do repositório que possuí essa solução para React, Next, Vue, Angular e Svelte, então não venha com desculpinha de que isso não funciona em tal linguagem, agora vamos lá!
Integração Automatizada com Swagger e Orval
Este post fornece um guia sobre como utilizar e integrar automaticamente o Swagger em suas aplicações frontend desenvolvidas com React, Next.js, Vue, Angular e Svelte, utilizando a poderosa ferramenta Orval. Com a integração automatizada do Swagger, você pode economizar tempo e garantir que sua documentação de API esteja sempre atualizada em suas aplicações.
O que é o Orval?
O Orval é uma biblioteca JavaScript que simplifica a integração do Swagger em projetos frontend. Ele oferece suporte para várias estruturas, incluindo React, Vue, Angular e Svelte, e automatiza a geração de código e a documentação da API a partir de uma especificação do Swagger. Isso permite que você mantenha seus aplicativos atualizados com as mudanças na API sem a necessidade de atualizações manuais.
Pré-requisitos
Antes de começar, certifique-se de ter o seu projeto React, Next.js, Vue, Angular ou Svelte já configurado, ou se quiser pode ver mais detalhes nos exemplos do repositório.
Instalação do Orval
Para começar, instale o Orval em seu projeto. Você pode fazê-lo executando o seguinte comando no diretório raiz do seu projeto:
npm install --save-dev orval
Configuração do Orval
Agora, você precisa configurar o Orval para o seu projeto. Crie um arquivo de configuração orval.config.js no diretório raiz do seu projeto com a seguinte estrutura:
// orval.config.cjs
module.exports = {
backend: {
output: {
mode: 'single', // Crie apenas um único arquivo contento todas as configurações
client: 'react-query', // O Cliente a ser usado
target: path.resolve(__dirname, './src/query.ts'), // Caminho de saída para o arquivo gerado
},
input: {
target: require.resolve('./swagger.json') // URL da especificação do Swagger
}
}
};
Substitua './swagger.json' pela URL da especificação do Swagger da sua API.
Agora adicione um script do orval no seu package.json
"orval": "orval --config ./orval.config.cjs"
Geração Automática de Código
Agora, você pode gerar automaticamente o código a partir da especificação do Swagger usando o Orval. Execute o seguinte comando no diretório raiz do seu projeto:
npm run orval
Isso criará um arquivo query.ts (ou o caminho especificado em backend -> target) em seu projeto, contendo definições de tipos e funções para interagir com sua API.
Uso em Projetos
Depois de gerar o código com o Orval, você pode usá-lo em seus projetos frontend. Importe as funções e tipos gerados em seus componentes ou serviços para começar a fazer chamadas à API.
Aqui está um exemplo de como usar as funções geradas em um componente React:
import { useGetUsers } from './query';
function MyComponent() {
const { data, isError, isLoading } = useGetUsers();
if (loading) {
return <p>Carregando...</p>;
}
if (error) {
return <p>Erro: {error.message}</p>;
}
return (
<div>
{data.map((user) => (
<div key={user.id}>{user.name}</div>
))}
</div>
);
}
Atualização Automática da Documentação da API
Com o Orval, você pode manter a documentação da API atualizada automaticamente em seu aplicativo. Sempre que houver mudanças na especificação do Swagger, basta executar novamente o comando npm run orval para regenerar o código e atualizar a documentação em seu projeto.
Conclusão
A integração automatizada do Swagger em aplicações usando o Orval simplifica o processo de desenvolvimento e garante que sua aplicação front-end esteja sempre em conformidade com a API. Aproveite essa ferramenta poderosa para economizar tempo e evitar erros manuais na integração do Swagger.
Para obter mais informações sobre o Orval e suas opções de configuração, consulte a documentação oficial em link para a documentação oficial.
Aviso: Lembre-se de manter suas dependências e código atualizados regularmente para evitar problemas de compatibilidade. E se você ou sua empresa não usam o Swagger para documentar suas APIs, agora é o momento para fazer isso.
Meu LinkedIn: Felipe Bergaschi
Repositório: github