Fastify Swagger: documentação OpenAPI com Zod
A documentar APIs Node.js de maneira inteligente usando Swagger e Zod com Fastify. Guia prático para gerar documentação automática e manter o seu time alinhado.
Por que isso é importante
Fastify Swagger: gere OpenAPI automático com @fastify/swagger + @fastify/swagger-ui + Zod (@fastify/type-provider-zod / jsonSchemaTransform). Schemas nas rotas viram /docs — documentação que acompanha o código, sem doc paralela mentindo.
Leitura relacionada: como criar API REST com Node.js · curso de Node.js · checklist de backend pleno · tipos de filas no RabbitMQ · Clean Vertical Sliced Architecture.
O que é o Swagger e por que documentar sua API?
Swagger é uma ferramenta de documentação para APIs que exibe todas as rotas, métodos e detalhes em um formato legível e interativo. Ao aplicar Swagger, você torna sua API facilmente compreendida e utilizável, tanto por sua equipe quanto por quem consome seus serviços.
Atenção
Documentação automática mitiga falhas de comunicação e mantém seu projeto sempre atualizado, evitando divergências perigosas entre o código e os endpoints descritos.
Como o Fastify integra com Swagger
O Fastify Swagger é um plugin que gera a documentação Swagger/OpenAPI de forma dinâmica e automática, aproveitando as informações que já existem nas rotas e schemas do seu backend Node.js. Com ele, você não precisa escrever um JSON manual de rotas ou descrições.
Atenção
Não utilizar o plugin correto pode trazer conflitos de versão e resultados inesperados. Sempre verifique as versões compatíveis do Fastify e plugins Swagger!
Preparando o ambiente: dependências essenciais
Antes de gerar sua documentação, instale o Fastify, Fastify Swagger, Fastify Swagger UI e o Zod para schemas tipados. É o primeiro passo para um fluxo de desenvolvimento realmente eficiente.
Instalando o Fastify Swagger e outros plugins
Com o ambiente configurado, instale as bibliotecas e integre o Fastify Swagger ao seu projeto. Use o comando via terminal (npm ou yarn) para agilizar o setup.
npm install fastify @fastify/swagger @fastify/swagger-ui @fastify/type-provider-zod zodAtenção
Não esqueça de instalar todas as dependências necessárias. Um plugin ausente trará erros ao rodar seu backend!
Configurando o Fastify Swagger passo a passo
O registro dos plugins no Fastify deve ocorrer antes das rotas. Dessa forma, a documentação abrange corretamente todos endpoints. Informe ao plugin os detalhes da API (nome, descrição, versão).
@fastify/swagger, @fastify/swagger-ui e @fastify/type-provider-zod (com jsonSchemaTransform) se usar Zod.app.register() e passe as opções de OpenAPI.Integração com Fastify Swagger UI
Ao adicionar o Fastify Swagger UI, você ganha uma interface visual pronta para explorar e testar as rotas documentadas. Isso economiza tempo durante desenvolvimento e facilita feedback rápido com o time.
Atenção
Após a configuração, acesse <code>localhost:3000/docs</code> para visualizar a documentação. O endpoint padrão pode variar, revise a configuração do seu projeto.
Schemas com Zod v4 e @fastify/type-provider-zod
Com @fastify/type-provider-zod, configure validatorCompiler/serializerCompiler e passe transform: jsonSchemaTransform ao @fastify/swagger. Assim Zod vira OpenAPI de forma consistente — confira a doc do pacote para a versão do Zod exigida.
jsonSchemaTransform do provedor
de Zod.app.withTypeProvider dentro de um app.after para garantir todos os plugins carregados.Bearer Authorize e $ref compartilhados no Swagger UI
Depois do /docs abrir, o gap vs tutoriais rasos é auth + reuso de schema. No register do @fastify/swagger (OpenAPI 3), coloque components.securitySchemes.bearerAuth com type http, scheme bearer, bearerFormat JWT. Nas rotas protegidas, schema.security: [{ bearerAuth: [] }]. No Swagger UI (@fastify/swagger-ui), o botão Authorize aparece — cole o JWT uma vez e teste as rotas autenticadas sem Postman.
Para $ref: registre schemas Zod compartilhados (User, ErrorBody) via z.globalRegistry / jsonSchemaTransform do @fastify/type-provider-zod e referencie-os nas responses — evita copiar o mesmo objeto em 10 rotas e mantém o OpenAPI limpo.
Pacote certo
Use @fastify/type-provider-zod (scoped). Imports mortos de fastify-type-provider-zod quebram build — confirme o nome no npm antes de colar snippet antigo.
Nota de upgrade: Zod v4 (zod/v4) no type-provider
Em 2026 a documentação e a SERP já citam Zod v4 com o type-provider atual. Se o projeto ainda está em Zod 3, planeje a migração e confira as notas oficiais do pacote — sem inventar breaking changes.
Endereçando possíveis erros de configuração
Ao rodar o servidor, pode acontecer de acessar uma rota incorreta, como <code>/docs</code> ao invés de <code>/documentation</code> . Corrija a rota conforme as configurações dos plugins.
Atenção
Se receber “Not found” ao acessar a documentação, confira o endpoint informado nos registros do Fastify Swagger UI.
Visualizando sua documentação criada automaticamente
Se tudo estiver correto, basta acessar a rota informada (geralmente <code>/docs</code> ). O Swagger UI exibirá todas as rotas documentadas sem necessidade de escrever documentos manualmente.
Documentação automática ou manual: quando usar cada uma
Swagger Automático via Plugin
Documentação gerada em tempo real pelo código
Prós
- Sempre atualizada
- Pouco esforço de manutenção
- Interface padrão
Contras
- Pode dificultar customizações complexas
- Dependente dos plugins
Documentação manual
Documentação redigida separadamente, independente do código
Prós
- Flexível para customizar
- Bom para APIs públicas com necessidades específicas
Contras
- Suscetível a desatualização
- Gasta mais tempo
Organização: refs compartilhados e pastas de schema
Sempre mantenha os plugins atualizados, padronize o uso de schemas e comentários em suas rotas, e publique a URL da documentação API para seu time. Automatize sempre que possível!
Checklist: Fastify Swagger + Zod no ar
Checklist de Implementação
Fontes
Revisão em agosto de 2026. Pacotes scoped (@fastify/swagger, @fastify/swagger-ui, @fastify/type-provider-zod) e transformações Zod→OpenAPI mudam com majors — confira a doc do dia. Tutorial prático, não especificação OpenAPI oficial.
<a href="https://github.com/fastify/fastify-swagger">@fastify/swagger</a>. <a href="https://fastify.dev/docs/latest/Reference/Type-Providers/">Fastify Type Providers</a>. <a href="https://swagger.io/specification/">OpenAPI Specification</a>.
Perguntas frequentes
Como gerar documentação Swagger/OpenAPI com Fastify?
Use @fastify/swagger + @fastify/swagger-ui e declare schema nas rotas: a documentação OpenAPI nasce do contrato do código, não de um doc manual paralelo.
Ainda uso o pacote fastify-swagger antigo?
Não para projetos novos. O caminho atual é o escopo @fastify/swagger e @fastify/swagger-ui; imports antigos sem o escopo ficam desatualizados.
Dá para usar Zod com Fastify e Swagger UI?
Sim. Com @fastify/type-provider-zod e jsonSchemaTransform você valida entrada/saída e expõe o mesmo contrato no Swagger UI.
Onde fica a interface /docs no Fastify?
Em geral no endpoint configurado pelo @fastify/swagger-ui (comum: /docs). Confirme o path no register do plugin do seu projeto.