Skip to content

Capítulo 3.5: Documentação Automática Swagger

Tempo de Estudo: 30 minutos

1. Documentação da API: Manual de Operações de uma Estação Espacial

Imagine que você é um novo astronauta chegando à ISS. Como você saberia qual botão faz o quê e como operar o braço robótico? Você precisaria de um manual detalhado e atualizado.

A documentação da API é o mesmo tipo de manual para desenvolvedores. Ela explica:

  • Quais "portas de acoplamento" (endpoints) estão disponíveis.
  • Quais "comandos" (métodos HTTP) podem ser enviados.
  • Qual "carga" (dados) precisa ser transmitida.
  • Qual "telemetria" (respostas) esperar.

O problema é que escrever a documentação manualmente é demorado, tedioso e quase sempre se torna desatualizado.

💡 Analogia espacial:

A documentação manual são projetos em papel que ficam no arquivo e não são atualizados após a modernização da estação. A documentação automática do FastAPI é um monitor interativo no Centro de Controle de Missões, que é atualizado em tempo real após cada mudança na estação.

2. A Magia do FastAPI: Como Funciona?

O FastAPI faz todo o "trabalho sujo" para você, com base no seu próprio código. Ele escaneia:

  1. Rotas: Todos os decoradores @app.get, @app.post, etc.
  2. Parâmetros: Parâmetros de caminho (ship_id: int) e de consulta.
  3. Modelos Pydantic: Seus "projetos" (Spaceship, SpaceshipCreate).
  4. Docstrings: Descrições que você escreve entre aspas triplas.

Com base nesses dados, o FastAPI gera um esquema de acordo com o padrão OpenAPI (anteriormente conhecido como Swagger) e depois o exibe através de duas interfaces bonitas.

3. Explorando o "Monitor do CCM": Swagger UI

Swagger UI é uma interface interativa que permite não apenas ler a documentação, mas também testar a API diretamente do navegador.

Abra http://127.0.0.1:8000/docs

Você verá:

  • Lista de endpoints: Agrupados por tags (por padrão, pelo nome do recurso) e coloridos com as cores dos métodos HTTP.
  • Descrições: Textos das suas docstrings ("""...""") são exibidos como descrições dos endpoints.
  • Parâmetros: Mostra quais parâmetros (como ship_id) o endpoint espera, seu tipo e obrigatoriedade.
  • Corpo da Requisição (Request Body): Para POST e PUT, mostra o esquema JSON gerado a partir do seu modelo Pydantic (SpaceshipCreate).
  • Respostas (Responses): Mostra os possíveis códigos de status e esquemas de resposta, baseados em response_model.
  • Botão "Try it out": Permite preencher os parâmetros e enviar uma requisição real para o seu servidor.

4. Melhorando a Documentação: Tags e Descrições

Vamos tornar nossa documentação ainda mais profissional.

Passo 1: Adicionar metadados ao FastAPI Ao criar app, você pode passar informações gerais sobre sua API.

Altere a linha app = FastAPI() em main.py: 

# main.py

app = FastAPI(
    title="Fleet Management API",
    description="API para gerenciamento de frota de naves espaciais.",
    version="1.0.0",
)
Agora, o título e a descrição aparecerão no topo da sua documentação.

Passo 2: Agrupar endpoints usando tags Você pode adicionar tags a cada endpoint para agrupá-los por significado.

Adicione o parâmetro tags aos decoradores: 

# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["Naves Espaciais"])
# ...

# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["Naves Espaciais"])
# ...

# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["Naves Espaciais"])
# ...

# e assim por diante para PUT e DELETE
Agora, todas as suas operações CRUD serão agrupadas ordenadamente sob o título "Naves Espaciais".

5. Visão Alternativa: ReDoc

O FastAPI fornece outra interface para documentação "pronta para uso" — ReDoc. Ela é menos interativa, mas é frequentemente considerada mais legível e excelente para documentação estática.

Abra http://127.0.0.1:8000/redoc

Você verá um layout de três colunas com navegação, descrições de endpoints e esquemas de dados. Esta é uma ótima maneira de fornecer documentação aos seus "clientes" (por exemplo, a equipe de frontend).

Quiz para Fixação

1. O FastAPI gera documentação com base em...

2. Qual padrão está na base da autodocumentação do FastAPI?

3. Qual é o URL padrão para acessar a documentação interativa Swagger UI?

4. O parâmetro `tags` no decorador `@app.get` é usado para:

5. ReDoc é...

🚀 Resumo do Capítulo:

Você viu uma das "superpotências" mais poderosas do FastAPI — a criação de documentação sem nenhum esforço.

  • 📖 Sua API agora tem dois tipos de documentação atualizada: Swagger UI e ReDoc.
  • 🔬 A documentação é interativa e permite testar a API em tempo real.
  • 🏷️ Você aprendeu a aprimorá-la com metadados e tags.

O manual de operações está pronto e sempre atualizado! No capítulo final desta seção, aprenderemos a lidar com "anomalias espaciais" — erros e dados incorretos.

📌 Verificação:

  • Certifique-se de que o título, a descrição e os endpoints agrupados por tags são exibidos em http://127.0.0.1:8000/docs.
  • Verifique se seu modelo Spaceship está visível na seção "Schemas".
  • Abra http://127.0.0.1:8000/redoc e avalie a visão alternativa.

⚠️ Se as alterações não aparecerem:

  • Certifique-se de que salvou o arquivo main.py.
  • Verifique que o servidor uvicorn está executando com a flag --reload e recarregou com sucesso.