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.
- Passo 1: Instale as dependências:
npm install fastify @fastify/swagger @fastify/swagger-ui @fastify/type-provider-zod zod - Passo 2: Importe os plugins no seu arquivo principal de
servidor Node.js. - Passo 3: Inicie a configuração, registrando os plugins antes de
declarar rotas.
Atençã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).
- Passo 1: Importe
@fastify/swagger,@fastify/swagger-uie@fastify/type-provider-zod(comjsonSchemaTransform) se usar Zod. - Passo 2: Configure o plugin usando
app.register()e passe as opções de OpenAPI. - Passo 3: Registre antes de todas as rotas.
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 localhost:3000/docs 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.
- Passo 1: Importe
jsonSchemaTransformdo provedor
de Zod. - Passo 2: Use
app.withTypeProviderdentro de umapp.afterpara garantir todos os plugins carregados. - Passo 3: Declare suas rotas usando os schemas tipados do Zod
normalmente.
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.
- openapi.components.securitySchemes.bearerAuth = { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }.
- Rotas protegidas: security: [{ bearerAuth: [] }] no schema da rota.
- Abra /docs → Authorize → cole o JWT no Bearer → Try it out.
- Extraia User/Error no registry Zod; deixe o transform gerar $ref entre rotas.
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 /docs ao invés de /documentation . 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 /docs ).
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
- Instalou fastify, @fastify/swagger, @fastify/swagger-ui, @fastify/type-provider-zod e zod
- Registrou plugins ANTES de criar rotas
- Configurou detalhes OpenAPI (nome, descrição, versão)
- Utilizou schemas Zod nas rotas
- Verificou o endpoint correto para documentação
- Testou se a documentação reflete as rotas corretamente
- Compartilhou a URL da documentação para a equipe
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.
@fastify/swagger. Fastify Type Providers. OpenAPI Specification.
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.
Continue explorando
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.
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.
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.