Skip to content

Capítulo 6.4: Documentação da API

Tempo de estudo: 30 minutos

1. Por que a documentação da API é necessária?

Imagine que lhe deram um controle remoto de uma nave espacial complexa sem uma única etiqueta nos botões. Você os pressionaria aleatoriamente, arriscando lançar a catapulta em vez de ligar a luz. A documentação da API são essas mesmas etiquetas e instruções.

Boa documentação:

  • Economiza tempo: Os desenvolvedores não precisam adivinhar quais endpoints existem, quais parâmetros eles aceitam e o que retornam.
  • Reduz erros: Uma descrição clara dos formatos de dados e códigos de erro ajuda a evitar o uso incorreto da API.
  • Simplifica a integração: A equipe de frontend pode trabalhar em paralelo com a equipe de backend, baseando-se na documentação como um contrato.
  • É o seu legado: Daqui a seis meses, você mesmo se agradecerá quando voltar ao projeto.

💡 Analogia espacial:

  • API = Sistema complexo de controle de uma estação espacial.
  • Documentação da API = Manual para astronautas. Descreve:
  • Qual comando (endpoint) enviar para abrir a eclusa.
  • Quais parâmetros (corpo da requisição) passar para configurar o sistema de suporte à vida.
  • Quais sinais (respostas da API) esperar em resposta.

2. Documentação no FastAPI: Magia Automática

FastAPI torna a documentação incrivelmente simples. Ele gera automaticamente documentação interativa com base no seu código, usando os padrões OpenAPI e Swagger UI.

Passo 1: Adicione metadados à sua aplicação

Em main.py, você pode adicionar descrições que aparecerão na documentação.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (código FastAPI)

app = FastAPI(
    title="SpaceAPI",
    description="""
API para exploração da galáxia. 🚀

Você poderá:
* **Visualizar planetas**.
* **Adicionar novos mundos** (autenticação necessária).
    """,
    version="1.0.0",
    contact={
        "name": "Engenheiro Chefe do Centro de Controle da Missão",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

Passo 2: Descreva seus modelos e endpoints

Quanto mais detalhadamente você descrever os modelos Pydantic e os parâmetros dos endpoints, melhor será a documentação.

# No arquivo de modelos Pydantic ou em main.py

class PlanetBase(BaseModel):
    name: str = Field(..., example="Terra", description="Nome do planeta")
    description: str = Field(..., example="Planeta azul com vida diversa", description="Breve descrição")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # ou from_attributes = True no Pydantic v2

# No arquivo de rotas
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="Obter lista de todos os planetas",
    description="Retorna uma lista de todos os planetas conhecidos com paginação (futuramente)."
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="Criar novo planeta",
    responses={
        401: {"description": "Usuário não autorizado"},
        422: {"description": "Erro de validação de dados"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...
  • Field(..., example="..."): Adiciona exemplos à documentação.
  • summary: Breve descrição do endpoint.
  • description: Descrição detalhada.
  • responses: Descrição de possíveis códigos de resposta, além do sucesso.

Passo 3: Abra a documentação no navegador

Inicie seu servidor FastAPI e abra duas URLs mágicas:

  1. http://127.0.0.1:8000/docs — abrirá a documentação interativa Swagger UI. Aqui você pode não apenas ler, mas também testar seus endpoints diretamente do navegador!
  2. http://127.0.0.1:8000/redoc — abrirá uma visão alternativa da documentação ReDoc. É menos interativa, mas frequentemente mais legível.

3. Documentação no Laravel: Usando pacotes de terceiros

Ao contrário do FastAPI, Laravel não gera documentação "out-of-the-box". No entanto, existem excelentes pacotes que fazem isso, analisando seu código. O mais popular é o Scribe.

Passo 1: Instalação do Scribe 

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

Passo 2: Descrevendo endpoints usando DocBlocks

Scribe lê os PHP DocBlocks (comentários do tipo /** ... */) acima dos métodos do seu controlador.

Abra app/Http/Controllers/PlanetController.php:

// app/Http/Controllers/PlanetController.php

/**
 * @group Planetas
 * API para gerenciamento de planetas
 */
class PlanetController extends Controller
{
    /**
     * Obter lista de planetas
     *
     * Retorna uma lista paginada de todos os planetas na galáxia.
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * Criar um novo planeta
     *
     * @authenticated
     *
     * @bodyParam name string required Nome do planeta. Example: Kepler-186f
     * @bodyParam description string required Descrição do planeta.
     * @bodyParam size_km integer required Diâmetro em quilômetros. Example: 14000
     * @bodyParam is_habitable boolean Se o planeta é habitável. Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "Primeiro planeta confirmado do tamanho da Terra na zona habitável de outra estrela.",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... e assim por diante para outros métodos
}

Tags chave do Scribe:

  • @group: Agrupa endpoints.
  • @unauthenticated / @authenticated: Indica se um token é necessário.
  • @bodyParam: Descreve um parâmetro no corpo da requisição.
  • @response: Exemplo de resposta de sucesso.

Passo 3: Geração e visualização da documentação

Cada vez que fizer alterações nos DocBlocks, execute o comando:

php artisan scribe:generate
Scribe criará uma página HTML estática com sua documentação. Abra-a no endereço: http://your-app-url/docs.

Quiz para fixação

1. FastAPI gera documentação com base no padrão:

2. Qual URL abre o Swagger UI no FastAPI por padrão?

3. Pacote popular para geração de documentação no Laravel:

4. No Scribe, a tag usada para descrever parâmetros do corpo da requisição é:

🚀 Conclusão do capítulo:

Você criou documentação profissional, transformando suas APIs de "caixas-pretas" em ferramentas compreensíveis e fáceis de usar.

  • ✅ Entendeu a importância crítica de documentar APIs.
  • 🪄 Aprendeu a usar a geração automática de documentação no FastAPI.
  • ⚙️ Dominou os fundamentos do pacote Scribe para documentar APIs no Laravel.
  • 🛰️ Confirmou que uma boa documentação é o melhor auxiliar para qualquer desenvolvedor.

Suas APIs agora não só funcionam e estão protegidas, mas também estão totalmente prontas para serem usadas por outros membros da equipe. Resta o último, mas mais importante passo — a verificação de segurança final.

📌 Verificação:

  • Para FastAPI: abra /docs no navegador e tente executar uma requisição GET para a lista de planetas diretamente da interface Swagger UI.
  • Para Laravel: execute php artisan scribe:generate e abra /docs. Certifique-se de que os endpoints estão agrupados e que o método store tem uma descrição de parâmetros.