FastAPI 'Hello World'

1 Introdução ao FastAPI

FastAPI é um framework web moderno em Python para construir APIs. Ele utiliza Starlette para a camada web e Pydantic para validação de dados. Dicas de tipo não são apenas decoração — elas impulsionam o parsing de requisições, serialização de respostas e documentação automática.

Rápido: Alto desempenho comparável a Node e Go.
Rápido para codificar: Desenvolva recursos rapidamente com o mínimo de código repetitivo.
Menos bugs: Valida entradas e saídas automaticamente.
Baseado em padrões: Gera OpenAPI, Swagger UI e ReDoc de forma integrada.

Quando estiver pronto, clique em “Próximo” e teremos um aplicativo mínimo rodando localmente.

2 Pré-requisitos: Python e Pip

Confirme se Python 3.7+ e pip estão instalados:

python --version
pip --version

Se estiverem faltando, instale a partir de python.org.

3 Configurar um Ambiente Virtual

Mantenha as dependências organizadas com um ambiente virtual.

python -m venv .venv

Ative-o:

# macOS/Linux
source .venv/bin/activate

# Windows (Prompt de Comando)
.venv\Scripts\activate

Você verá (.venv) quando estiver ativo.

4 Instalar FastAPI e Uvicorn

Instale FastAPI e Uvicorn (o servidor ASGI) dentro do seu ambiente virtual:

pip install "fastapi[all]" uvicorn[standard]

O extra [all] inclui Pydantic v2 e dependências opcionais padrão. Se você prefere instalações mais leves, use pip install fastapi uvicorn.

5 Criar main.py

Crie um arquivo chamado main.py e adicione um endpoint básico:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Olá, FastAPI"}

É isso — uma importação, um aplicativo, uma rota. As docstrings e dicas de tipo alimentarão os documentos gerados.

6 Executar o Servidor com Uvicorn

Inicie o servidor com hot-reload durante o desenvolvimento:

uvicorn main:app --reload

Abra http://127.0.0.1:8000/ para ver sua resposta JSON.

7 Explorar Documentos Interativos

FastAPI serve Swagger UI e ReDoc automaticamente:

Swagger UI: /docs
ReDoc: /redoc
Schema OpenAPI: /openapi.json

Você pode testar o endpoint diretamente dos documentos e ver os modelos de requisição/resposta sem nenhuma configuração adicional.

8 Adicionar uma Rota com um Parâmetro de Rota

Atualize main.py com uma rota parametrizada:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Olá, FastAPI"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    result = {"item_id": item_id}
    if q:
        result["q"] = q
    return result

Graças às dicas de tipo, item_id será validado como um inteiro e documentado automaticamente.

9 Aceitar um Corpo de Requisição (Pydantic)

Defina um modelo e aceite payloads JSON:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []


@app.post("/items/", response_model=Item)
def create_item(item: Item):
    # Normalmente você armazenaria isso; aqui apenas o ecoamos de volta.
    return item


@app.get("/")
def read_root():
    return {"message": "Olá, FastAPI"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    result = {"item_id": item_id}
    if q:
        result["q"] = q
    return result

FastAPI valida o JSON, impõe tipos e documenta o modelo no schema gerado.

10 Levantar e Lidar com Erros

Use HTTPException para respostas de erro limpas:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []


db: dict[int, Item] = {}


@app.post("/items/", response_model=Item)
def create_item(item: Item):
    new_id = len(db) + 1
    db[new_id] = item
    return item


@app.get("/items/{item_id}")
def read_item(item_id: int):
    item = db.get(item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item não encontrado")
    return {"item_id": item_id, **item.dict()}

Agora, tentar um ID inexistente retorna um JSON 404 limpo: {"detail": "Item não encontrado"}.

11 Próximos Passos e Implantação

Fixar dependências: pip freeze > requirements.txt
Experimentar o modo de produção: uvicorn main:app --host 0.0.0.0 --port 8000
Implantar no Render, Fly.io, Railway, ou em uma VM com workers Gunicorn + Uvicorn
Usar @app.exception_handler para centralizar a formatação de erros
Proteger endpoints com OAuth2/JWT via fastapi.security

Agora você tem uma API funcional, validação e documentação ao vivo. A partir daqui, você pode expandir rotas, camadas e testes sem trocar de framework.

Progresso do Tutorial