# Guia completo: documentar API Swagger com OpenAPI passo a passo

> O guia completo de documentação de API Swagger com OpenAPI apresenta um passo a passo para criar documentação clara e testável. Swagger e OpenAPI permitem gerar especificações padronizadas desde o início até o deploy. A abordagem facilita a colaboração entre equipes e garante que a documentação seja funcional e amigável para desenvolvedores.

*Blog Sem Juízo · Novidades · 22 de julho de 2026 · Babi Cordeiro*

Quer documentar sua API sem dor de cabeça? Este guia mostra como usar Swagger e OpenAPI para criar uma documentação clara, testável e que seus colegas vão amar. Do zero até o deploy.

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](https://editor.swagger.io) é 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-openapi para Spring Boot, swagger-jsdoc para Node.js)

Se você usa Spring Boot, a configuração é quase automática com a dependência:

 org.springdoc springdoc-openapi-starter-webmvc-ui 2.5.0 

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](https://openapi-generator.tech) 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).

---

Fonte (canonical): https://blogsemjuizo.com.br/novidades/guia-completo-documentar-api-swagger-com-openapi-passo-a-passo/