Olá, devs! Neste post, vamos aprender como gerar documentação automática para uma API em uma aplicação Fastify utilizando as bibliotecas @fastify/swagger e Zod. Vamos dividir o tutorial em etapas para facilitar o entendimento.
O que é Fastify?
Fastify é um framework web altamente eficiente e focado em performance para Node.js. Ele oferece uma API simples e fácil de usar, com suporte para plugins e várias funcionalidades, tornando-o ideal para criar aplicações e APIs rápidas.
O que é Swagger?
Swagger é uma ferramenta popular que permite a criação de documentação interativa para APIs RESTful. Com Swagger, você pode visualizar e testar suas APIs diretamente na documentação, facilitando a vida dos desenvolvedores e consumidores da API.
Vantagens de Usar Swagger:
- Interatividade: Permite que os desenvolvedores testem as APIs diretamente na documentação.
- Clareza: Melhora a compreensão da API para desenvolvedores e usuários.
O que Vamos Precisar?
Este artigo requer conhecimento básico de Fastify e TypeScript.
- Uma aplicação Fastify configurada com TypeScript.
- As bibliotecas
@fastify/swagger,zodefastify-type-provider-zod.
Passo 1: Configurando o Projeto
Primeiro, vamos criar uma nova aplicação Fastify. Caso ainda não tenha um projeto, você pode criar um utilizando o seguinte comando:
npm init -y
npm install fastify
npm install -D typescript @types/node tsx
Após a instalação, crie um arquivo tsconfig.json com o seguinte conteúdo:
{
"$schema": "https://json.schemastore.org/tsconfig",
"_version": "20.1.0",
"compilerOptions": {
"lib": ["es2023"],
"module": "node16",
"target": "es2022",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"moduleResolution": "node16"
}
}
Crie uma estrutura de pastas para o seu projeto:
mkdir src
touch src/server.ts
Passo 2: Instalando as Dependências Necessárias
Agora, instale as bibliotecas necessárias para a geração da documentação:
npm install @fastify/swagger @fastify/swagger-ui fastify-type-provider-zod zod
Passo 3: Configurando o Fastify com Swagger
Abra o arquivo src/server.ts e adicione a configuração do Fastify e do Swagger:
import fastifySwagger from "@fastify/swagger";
import fastifySwaggerUi from "@fastify/swagger-ui";
import fastify from "fastify";
import {
jsonSchemaTransform,
serializerCompiler,
validatorCompiler,
ZodTypeProvider
} from "fastify-type-provider-zod";
import z from "zod";
const app = fastify();
// Adicionar o validator e o serializer compiler
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.register(fastifySwagger, {
openapi: {
info: {
title: 'API de Exemplo',
description: 'Documentação da API de exemplo utilizando Fastify',
version: '1.0.0',
},
},
// Importante adicionar para fazer o parse do schema
transform: jsonSchemaTransform
})
app.register(fastifySwaggerUi, {
routePrefix: '/docs'
})
// Definição de um endpoint de exemplo
app.after(() => {
app.withTypeProvider<ZodTypeProvider>().get('/hello', {
schema: {
response: {
200: z.object({
message: z.string(),
}),
},
},
}, async (request, reply) => {
return reply.send({ message: 'Hello world!' })
});
})
app
.listen({ port: 3333 })
.then(() => console.log('Server running on http://localhost:3333'))
Passo 4: Executando a Aplicação
Agora, você pode executar a aplicação usando o tsx, adicione um script no package.json para executar:
...
"scripts": {
"dev": "tsx watch src/server.ts"
},
...
npm run dev
Ao acessar http://localhost:3000/docs, você verá a interface do Swagger UI com a documentação gerada automaticamente para o endpoint /hello.
Passo 5: Adicionando mais endpoints e schemas
Você pode facilmente adicionar mais endpoints e esquemas à sua API. Por exemplo, vamos adicionar um endpoint para calcular a soma de dois números:
// Definição do esquema para a requisição
const sumSchema = z.object({
a: z.coerce.number(),
b: z.coerce.number(),
});
// Endpoint para calcular a soma
app.after(() => {
app.withTypeProvider<ZodTypeProvider>().get('/sum', {
schema: {
querystring: sumSchema,
response: {
200: z.object({
result: z.number(),
}),
},
},
}, async (request, reply) => {
const { a, b } = request.query
const result = a + b;
return { result };
});
})
Após adicionar o endpoint, a documentação do Swagger será atualizada automaticamente, permitindo que você visualize e teste a nova funcionalidade.
Bônus: Separando Rotas em Arquivos
Em alguns casos, você pode querer separar as rotas em arquivos distintos para manter a organização do seu código. Para isso, você pode utilizar os plugins do Fastify.
Aqui está um exemplo de como criar uma rota /sum em um arquivo separado:
Arquivo plugin.ts
import { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
import z from "zod";
const sumSchema = z.object({
a: z.coerce.number(),
b: z.coerce.number(),
});
export const sumRoute: FastifyPluginAsyncZod = async app => {
app.get('/sum', {
schema: {
querystring: sumSchema,
response: {
200: z.object({
result: z.number(),
}),
}
}
}, async (request, reply) => {
const { a, b } = request.query
const result = a + b;
return { result };
})
}
Atualizando o index.ts
Atualize o arquivo index.ts para registrar a nova rota:
import fastifySwagger from "@fastify/swagger";
import fastifySwaggerUi from "@fastify/swagger-ui";
import fastify from "fastify";
import {
jsonSchemaTransform,
serializerCompiler,
validatorCompiler
} from "fastify-type-provider-zod";
import { sumRoute } from "./plugin";
const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.register(fastifySwagger, {
openapi: {
info: {
title: 'API de Exemplo',
description: 'Documentação da API de exemplo utilizando Fastify',
version: '1.0.0',
},
},
transform: jsonSchemaTransform
})
app.register(fastifySwaggerUi, {
routePrefix: '/docs'
})
app.register(sumRoute)
app
.listen({ port: 3333 })
.then(() => console.log('Server running on http://localhost:3333'))
Conclusão
Pronto! Agora você tem uma aplicação Fastify com TypeScript capaz de gerar documentação automática utilizando @fastify/swagger e zod. Essa abordagem não apenas melhora a legibilidade da sua API, mas também facilita a vida dos desenvolvedores que a utilizam.
Espero que este tutorial tenha sido útil para você. Se tiver alguma dúvida, deixe um comentário abaixo. Até a próxima!
Gostou deste post? Siga-me para mais conteúdos sobre desenvolvimento web e tecnologias! 🚀
Top comments (0)