Jak definiujesz routes (operacje ścieżek)?

Question

Accepted Answer

W FastAPI **operacja ścieżki** to trasa — funkcja ozdabiacz za pomocą dekoratora metody HTTP (`@app.get`, `@app.post`, itp.), która obsługuje żądania do ścieżki. Wartość zwracana funkcji jest automatycznie serializowana do JSON.

## Definiowanie tras dla każdej metody 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}
```

Każdy dekorator mapuje metodę HTTP + ścieżkę do handlera. Nazwa funkcji należy do Ciebie; dekorator definiuje trasę. Zwrócone słowniki/listy/modele Pydantic są automatycznie serializowane do JSON — bez ręcznego `json.dumps`.

## Kolejność ma znaczenie dla nakładających się ścieżek

```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 dopasowuje trasy w kolejności deklaracji, więc umieszczaj ścieżki statyczne przed dynamicznymi.

## Metadane operacji (zasilają dokumentację)

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

Parametry dekoratora (`tags`, `summary`, `status_code`, `response_model`) konfigurują zachowanie i wzbogacają automatycznie generowaną dokumentację.

## Dlaczego to ważne

Operacje ścieżek są podstawą każdej aplikacji FastAPI — definiują punkty końcowe Twojego API i sposób obsługi żądań.

Zrozumienie wzorca decorator-per-HTTP-method, że wartości zwracane są automatycznie serializowane do JSON (bez boilerplate'u), że wyrażenia typu na parametrach napędzają konwersję i validację oraz że kolejność tras ma znaczenie dla nakładających się ścieżek, jest niezbędną codzienną wiedzą do budowania dowolnego punktu końcowego.

Metadane dekoratora również zasilają automatyczną dokumentację FastAPI, bezpośrednio łącząc trasy z dokumentami.

To jest pierwsza i najfundamentalna rzecz do opanowania w FastAPI.