Como você define rotas (operações de caminho)?

Question

Accepted Answer

No FastAPI, uma **operação de caminho** é uma rota — uma função decorada com um decorador de método HTTP (`@app.get`, `@app.post`, etc.) que manipula solicitações para um caminho. O valor de retorno da função é automaticamente serializado para JSON.

## Definindo rotas para cada método HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Cada decorador mapeia um método HTTP + caminho para um handler. O nome da função é seu; o decorador define a rota. Dicts/listas/modelos Pydantic retornados são serializados automaticamente para JSON — sem `json.dumps` manual.

## A ordem importa para caminhos sobrepostos

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI corresponde rotas na ordem de declaração, então coloque caminhos estáticos antes dos dinâmicos.

## Metadados de operação (alimentam a documentação)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Os parâmetros do decorador (`tags`, `summary`, `status_code`, `response_model`) configuram o comportamento e enriquecem a documentação gerada automaticamente.

## Por que isso importa

Operações de caminho são a base de cada aplicação FastAPI — elas definem os endpoints da sua API e como as solicitações são manipuladas.

Compreender o padrão decorator-per-HTTP-method, que os valores de retorno são automaticamente serializados para JSON (sem boilerplate), que as dicas de tipo nos parâmetros direcionam conversão e validação, e que a ordem das rotas importa para caminhos sobrepostos é conhecimento essencial do dia a dia para construir qualquer endpoint.

Os metadados do decorador também alimentam a documentação automática do FastAPI, vinculando rotas diretamente aos documentos.

Este é o primeiro e mais fundamental conceito a dominar no FastAPI.