Senta que lá vem história: você passou horas construindo uma API linda, mas na hora de explicar pra outra pessoa como usar, o negócio vira um caos. A gente já passou por isso, e descobriu que documentar API com Swagger não é só uma frescura de dev organizado. É o que separa uma API que todo mundo ama de uma que ninguém quer encostar.
O Swagger, hoje parte da especificação OpenAPI, é um conjunto de ferramentas open source que permite descrever sua API REST de forma padronizada. Com ele, você cria um arquivo YAML ou JSON que vira uma documentação interativa, testável e que se atualiza sozinha. Neste guia, você vai aprender o passo a passo para documentar sua API do zero, com dicas da prática e os erros que a gente já cometeu pra você não repetir.
Pré-requisitos
Antes de começar, você vai precisar de:
- Uma API REST funcionando (pode ser em qualquer linguagem: Node.js, Python, Java, PHP, etc.)
- Conhecimento básico de HTTP (métodos GET, POST, PUT, DELETE, códigos de status)
- Um editor de texto ou IDE (VS Code, IntelliJ, ou o próprio Swagger Editor online)
- Vontade de deixar sua API mais amigável (essa parte a gente garante que vai acontecer)
Passo 1: Entender a especificação OpenAPI
A especificação OpenAPI (antes conhecida como Swagger Specification) é um padrão aberto para descrever APIs REST. Imagine que é um contrato: você diz quais endpoints existem, quais parâmetros eles aceitam, o que retornam e como a autenticação funciona.
O arquivo pode ser escrito em YAML ou JSON. A gente recomenda YAML, é mais legível e menos verboso. A estrutura básica tem:
- openapi: versão da especificação (use 3.0.0 ou superior)
- info: título, descrição e versão da sua API
- paths: os endpoints e suas operações
- components: schemas reutilizáveis (modelos de dados, parâmetros, security schemes)
Dica de quem já errou: não tente escrever tudo de uma vez. Comece com um único endpoint e vá expandindo. É mais fácil testar e corrigir.
Erro comum: usar versões antigas da especificação (2.0). A OpenAPI 3.0 trouxe melhorias como suporte a exemplos, links e callbacks. Fique na versão atual.
Passo 2: Criar o arquivo de especificação
Você pode criar o arquivo manualmente ou usar geradores automáticos. Vamos pelo caminho manual primeiro, assim você entende cada parte.
Crie um arquivo chamado api-docs.yaml ou swagger.yaml na raiz do seu projeto. Comece com:
openapi: 3.0.0 info: title: Minha API de Tarefas description: API para gerenciar tarefas do dia a dia version: 1.0.0
Agora adicione um endpoint. Por exemplo, uma rota GET que lista tarefas:
paths: /tarefas: get: summary: Lista todas as tarefas operationId: listarTarefas responses: '200': description: Lista de tarefas content: application/json: schema: type: array items: $ref: '#/components/schemas/Tarefa'
Veja que usamos $ref para referenciar um schema que ainda não definimos. Vamos criar o schema no bloco components:
components: schemas: Tarefa: type: object properties: id: type: integer titulo: type: string concluida: type: boolean required:
- titulo
Dica: coloque exemplos nos schemas. Eles aparecem na documentação interativa e ajudam quem está testando.
Erro comum: esquecer de definir os campos obrigatórios. Sem required, o Swagger não valida que o campo é necessário, e sua documentação fica incompleta.
Passo 3: Adicionar autenticação
Se sua API exige autenticação, você precisa declarar no arquivo. O Swagger suporta vários tipos: API Key, HTTP (Bearer, Basic), OAuth2, OpenID Connect.
Exemplo com Bearer Token (JWT):
components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
security:
- bearerAuth: []
Depois, nos endpoints que exigem autenticação, você pode sobrescrever ou remover o security. Por exemplo, um endpoint público de login não precisa de token.
Dica: teste a autenticação no Swagger UI antes de compartilhar a documentação. Nada mais frustrante que um botão "Authorize" que não funciona.
Erro comum: colocar a chave security no nível global e esquecer de liberar endpoints públicos. Use security: [] no endpoint específico para desabilitar.
Passo 4: Usar o Swagger Editor para validar
O Swagger Editor é uma ferramenta online que valida seu arquivo em tempo real. Cole o YAML que você criou e veja se aparece algum erro em vermelho.
Erros comuns que o editor pega:
- Indentação errada (YAML é sensível a espaços)
- Referência a schema que não existe
- Tipo de dado inválido
- Caminho duplicado
Dica: use a versão offline do Swagger Editor se você trabalha sem internet. Dá pra rodar via Docker.
Erro comum: ignorar os warnings do editor. Um warning não quebra a documentação, mas pode indicar má prática. Por exemplo, falta de description nos parâmetros.
Passo 5: Gerar a documentação interativa com Swagger UI
O Swagger UI é a ferramenta que transforma seu arquivo YAML em uma página web interativa. Você pode:
- Usar a versão online hospedada (ex.: petstore.swagger.io)
- Baixar os arquivos estáticos e hospedar no seu servidor
- Usar bibliotecas específicas da sua linguagem (ex.:
springdoc-openapipara Spring Boot,swagger-jsdocpara Node.js)
Se você usa Spring Boot, a configuração é quase automática com a dependência:
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.5.0</version> </dependency>
Depois, acesse http://localhost:8080/swagger-ui.html e pronto, sua documentação está no ar.
Dica: personalize o CSS do Swagger UI para usar as cores da sua empresa. Dá pra fazer com um arquivo CSS customizado.
Erro comum: esquecer de configurar o CORS no servidor. Se o Swagger UI estiver em um domínio diferente da sua API, as requisições de teste vão falhar.
Passo 6: Manter a documentação sincronizada
Documentação desatualizada é pior que documentação nenhuma. A melhor prática é gerar o arquivo OpenAPI a partir do código (code-first) ou validar o código contra a especificação (design-first).
Code-first: você escreve a API e usa anotações ou decorators para gerar a especificação automaticamente. Ex.: @ApiOperation no Spring, @swagger no FastAPI.
Design-first: você escreve a especificação primeiro e gera o código a partir dela. Ferramentas como OpenAPI Generator fazem isso.
Dica: integre a validação no seu pipeline de CI/CD. Ex.: um job que roda o swagger-cli validate a cada push.
Erro comum: confiar 100% na geração automática e não revisar. Às vezes o gerador omite detalhes importantes, como exemplos ou descrições de erros.
Checklist: o que você fez até aqui
- [ ] Entendeu a estrutura da especificação OpenAPI
- [ ] Criou um arquivo YAML com info, paths e components
- [ ] Adicionou autenticação (se necessário)
- [ ] Validou o arquivo no Swagger Editor
- [ ] Configurou o Swagger UI no seu projeto
- [ ] Estabeleceu um processo para manter a documentação atualizada
Perguntas frequentes
O que é Swagger?
Swagger é um conjunto de ferramentas open source para trabalhar com a especificação OpenAPI. Inclui o Swagger Editor (para criar/editar), Swagger UI (para visualizar/testar) e Swagger Codegen (para gerar código). A especificação em si chama-se OpenAPI.
Qual a diferença entre Swagger e OpenAPI?
OpenAPI é a especificação (o padrão). Swagger é a implementação original que deu origem ao padrão. Hoje, a OpenAPI Initiative mantém a especificação, e o termo Swagger ainda é usado para as ferramentas. Na prática, os nomes são usados como sinônimos.
Preciso escrever o YAML na mão?
Não necessariamente. Muitos frameworks geram automaticamente a partir de anotações no código. Mas entender o YAML ajuda a personalizar e corrigir quando a geração automática não atende.
Como testar minha API pelo Swagger UI?
No Swagger UI, cada endpoint tem um botão "Try it out". Clique, preencha os parâmetros (se houver) e clique em "Execute". A resposta aparece abaixo, com status, headers e corpo.
O Swagger funciona com APIs que não são REST?
A especificação OpenAPI foi feita para APIs REST. Para outros tipos (GraphQL, SOAP, gRPC), existem ferramentas específicas. Mas você pode usar o Swagger para documentar endpoints REST que coexistem com outras arquiteturas.
Como versionar a documentação?
Use o campo version no bloco info do YAML. Quando sua API muda, incremente a versão. Ferramentas como Swagger UI permitem exibir múltiplas versões. No código, mantenha arquivos separados (ex.: api-v1.yaml, api-v2.yaml).