Как вы определяете маршруты (операции пути)?

Question

Accepted Answer

В FastAPI **операция пути** — это маршрут — функция, украшенная декоратором метода HTTP (`@app.get`, `@app.post` и т. д.), которая обрабатывает запросы к пути. Возвращаемое значение функции автоматически сериализуется в JSON.

## Определение маршрутов для каждого метода 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}
```

Каждый декоратор отображает метод HTTP + путь на обработчик. Имя функции — ваше; декоратор определяет маршрут. Возвращаемые словари/списки/модели Pydantic автоматически сериализуются в JSON — без ручного `json.dumps`.

## Порядок имеет значение для перекрывающихся путей

```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 сопоставляет маршруты в порядке объявления, поэтому статические пути должны идти перед динамическими.

## Метаданные операции (питают документацию)

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

Параметры декоратора (`tags`, `summary`, `status_code`, `response_model`) настраивают поведение и обогащают автоматически генерируемую документацию.

## Почему это важно

Операции пути — это основа каждого приложения FastAPI — они определяют конечные точки вашего API и то, как обрабатываются запросы.

Понимание паттерна decorator-per-HTTP-method, того, что возвращаемые значения автоматически сериализуются в JSON (без шаблонного кода), что подсказки типов на параметрах управляют преобразованием и валидацией, и что порядок маршрутов имеет значение для перекрывающихся путей, — это необходимые повседневные знания для построения любой конечной точки.

Метаданные декоратора также питают автоматическую документацию FastAPI, напрямую связывая маршруты с документацией.

Это первое и самое фундаментальное, что нужно освоить в FastAPI.