FastAPI: validação e docs

Neste capítulo você vai refinar validação, respostas de erro e leitura das docs. O projeto-fio é o Ateliê Boa Viagem, ateliê digital fictício em Boa Viagem, Recife.

Seu ponto de partida

Use o exemplo 25-fastapi-validacao do pacote anexo e copie inicio/ para uma pasta de prática fora do original. A raiz do exemplo é a referência completa desta etapa.

Use servidor só em 127.0.0.1 quando o README do exemplo pedir HTTP local. Abrir ou testar não publica nada.

Como praticar

Leia → copie ou digite → mude uma coisa → preveja → salve → recarregue → confira. Restaure cada experiência antes da próxima. Faça as atividades antes de abrir as respostas comentadas.

Respostas explícitas

Use HTTPException para 404. Documente response_model.

Faça na sua cópia

Confira o trecho no contexto do exemplo antes de mudar.

from fastapi import HTTPException
raise HTTPException(status_code=404, detail='Tarefa não encontrada')

Mude uma coisa e preveja

Padronize a mensagem de 404.

Anote o que espera observar antes de salvar e recarregar.

Recarregue e confira

detail claro no JSON.

Se não acontecer

Importe HTTPException.

Query params tipados

Filtre ?feita=true com parâmetro bool.

Faça na sua cópia

Confira o trecho no contexto do exemplo antes de mudar.

@app.get('/tarefas')
def listar(feita: bool | None = None):
    ...

Mude uma coisa e preveja

Filtre só tarefas abertas.

Anote o que espera observar antes de salvar e recarregar.

Recarregue e confira

Query altera a lista.

Se não acontecer

Compare com t.feita.

Fechar o módulo Python API

Você viu Django (páginas) e FastAPI (API). Ambos locais. Escolha no fechamento conforme o problema.

Faça na sua cópia

Confira o trecho no contexto do exemplo antes de mudar.

Django → HTML servidor
FastAPI → JSON API

Mude uma coisa e preveja

Anote um caso de uso para cada.

Anote o que espera observar antes de salvar e recarregar.

Recarregue e confira

Notas pessoais prontas para o volume 32.

Se não acontecer

Não há resposta única.

Atividades

Atividade 1

Quando usar HTTPException?

Atividade 2

O que response_model documenta?

Atividade 3

Django e FastAPI resolvem o mesmo problema sempre?

Respostas comentadas

Resposta da atividade 1

Erros HTTP conscientes (404, 400…).

Resposta da atividade 2

Formato de saída na OpenAPI/docs.

Resposta da atividade 3

Não; páginas vs API é um eixo típico.

O arquivo completo

Referência do exemplo 25-fastapi-validacao, reproduzida aqui para que você possa conferir sem sair da página.

main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="Tarefas do Ateliê")
tarefas: list[dict] = []
seq = 0

class TarefaIn(BaseModel):
    titulo: str = Field(min_length=3)
    feita: bool = False

@app.get("/tarefas")
def listar(feita: bool | None = None):
    if feita is None:
        return tarefas
    return [t for t in tarefas if t["feita"] is feita]

@app.post("/tarefas", status_code=201)
def criar(body: TarefaIn):
    global seq
    seq += 1
    t = {"id": seq, **body.model_dump()}
    tarefas.append(t)
    return t

@app.get("/tarefas/{id}")
def detalhe(id: int):
    for t in tarefas:
        if t["id"] == id:
            return t
    raise HTTPException(status_code=404, detail="Tarefa não encontrada")