Noções Básicas de FastAPI

10 exemplos para você começar com FastAPI - 7 básicos e 3 intermediários.

Pré-requisitos

uv venv && source .venv/bin/activate
uv pip install "fastapi[standard]>=0.115" uvicorn httpx

• FastAPI 0.115+ no Python 3.14 usa Pydantic 2 para validação.
• Inicie o servidor de desenvolvimento com fastapi dev main.py.

Exemplos Básicos

1. API Hello World

App mínimo com docs OpenAPI automáticos.

from fastapi import FastAPI
 
app = FastAPI(title="API de Demonstração")
 
@app.get("/")
def read_root() -> dict[str, str]:
    return {"message": "Olá, FastAPI"}

• FastAPI() cria o objeto de aplicação ASGI.
• Type hints de retorno aparecem no esquema gerado em /docs.
• Execute com uvicorn main:app --reload ou fastapi dev main.py.

Relacionado: Modelos de Requisição e Resposta - corpos de requisição tipados

2. Parâmetros de Path

Capture valores tipados do path da URL.

from fastapi import FastAPI, HTTPException
 
app = FastAPI()
 
@app.get("/users/{user_id}")
def get_user(user_id: int) -> dict[str, int]:
    if user_id < 1:
        raise HTTPException(status_code=404, detail="Usuário não encontrado")
    return {"user_id": user_id}

• Nomes de parâmetros de path devem corresponder ao template da rota.
• FastAPI converte tipos e retorna 422 em caso de entrada inválida.
• Use HTTPException para respostas 4xx explícitas.

Relacionado: Middleware e Tratamento de Erros - corpos de erro consistentes

3. Parâmetros de Query

Filtros opcionais e paginação da string de query.

from fastapi import FastAPI, Query
 
app = FastAPI()
 
@app.get("/items")
def list_items(
    skip: int = Query(0, ge=0),
    limit: int = Query(20, ge=1, le=100),
    q: str | None = None,
) -> dict[str, object]:
    return {"skip": skip, "limit": limit, "q": q}

• Query() adiciona metadados de validação além de um padrão simples.
• Parâmetros opcionais usam str | None = None.
• Restrições como ge e le aparecem no OpenAPI.

4. Corpo de Requisição JSON

POST JSON validado por modelos Pydantic 2.

from fastapi import FastAPI
from pydantic import BaseModel, Field
 
app = FastAPI()
 
class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
 
@app.post("/items", status_code=201)
def create_item(item: ItemCreate) -> ItemCreate:
    return item

• O tipo do corpo é inferido da anotação do parâmetro.
• Falhas de validação retornam 422 com detail em nível de campo.
• Use modelos de entrada e saída separados nas fronteiras da API.

Relacionado: Modelos de Requisição e Resposta - filtragem com response_model

5. Filtragem de Modelo de Resposta

Oculte campos internos de respostas serializadas.

from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class UserIn(BaseModel):
    username: str
    password: str
 
class UserOut(BaseModel):
    username: str
 
@app.post("/users", response_model=UserOut)
def create_user(user: UserIn) -> UserIn:
    return user

• response_model controla tanto o OpenAPI quanto o payload JSON.
• Nunca retorne objetos ORM sem um esquema de resposta explícito.
• Senhas nunca devem aparecer em modelos de resposta.

6. Docs OpenAPI Automáticos

Swagger UI interativo incluído com cada app.

from fastapi import FastAPI
 
app = FastAPI(
    title="API de Inventário",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
)
 
@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}

• Acesse /docs para Swagger UI e /redoc para ReDoc.
• Desative os docs em produção com docs_url=None quando a política exigir.
• Docstrings de rota e tags enriquecem a especificação gerada.

7. Códigos de Status e Cabeçalhos

Defina semânticas HTTP em respostas de sucesso.

from fastapi import FastAPI, Response
 
app = FastAPI()
 
@app.post("/notify", status_code=202)
def enqueue(response: Response) -> dict[str, str]:
    response.headers["X-Job-Id"] = "job-42"
    return {"status": "accepted"}

• Use 201 para criações, 202 para aceitação assíncrona, 204 para corpos vazios.
• Injete Response para definir cabeçalhos sem alterar o tipo do corpo.
• Documente códigos de sucesso não-200 no OpenAPI com responses={}.

Exemplos Intermediários

8. Injeção de Dependência com Depends

Compartilhe sessões e configurações entre rotas.

from collections.abc import Generator
from fastapi import Depends, FastAPI
 
app = FastAPI()
 
def get_db() -> Generator[dict[str, str], None, None]:
    db = {"connected": "true"}
    yield db
 
@app.get("/items")
def list_items(db: dict[str, str] = Depends(get_db)) -> dict[str, str]:
    return db

• Depends resolve provedores uma vez por requisição.
• Use yield para configuração e desmontagem de conexões.
• Substitua dependências em testes via app.dependency_overrides.

Relacionado: Injeção de Dependência - sub-dependências e escopos

9. Módulos APIRouter

Divida APIs grandes em roteadores de funcionalidades.

from fastapi import APIRouter, FastAPI
 
users_router = APIRouter(prefix="/users", tags=["users"])
 
@users_router.get("/")
def list_users() -> list[str]:
    return ["ada", "grace"]
 
app = FastAPI()
app.include_router(users_router)

• APIRouter agrupa endpoints com prefixo e tags compartilhados.
• Um roteador por domínio mantém os arquivos de fácil manutenção.
• Monte roteadores de pacotes de funcionalidades para imports limpos.

Relacionado: Implantando FastAPI - layout de projeto de produção

10. Handler de Rota Assíncrono

I/O não bloqueante com endpoints async def.

import httpx
from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/external")
async def proxy() -> dict[str, str]:
    async with httpx.AsyncClient() as client:
        resp = await client.get("https://httpbin.org/get", timeout=5.0)
    return {"status": str(resp.status_code)}

• Use async def ao aguardar I/O de HTTP, banco de dados ou cache.
• Não chame bibliotecas bloqueantes dentro de rotas assíncronas sem run_in_threadpool.
• Emparelhe rotas assíncronas com drivers de banco de dados assíncronos como asyncpg.

Relacionado: Rotas Assíncronas e Bancos de Dados - sessões SQLAlchemy assíncronas

Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.