როგორ განსაზღვრავთ მარშრუტებს (path operations)?

Question

Accepted Answer

FastAPI-ში, **path operation** არის მარშრუტი — ფუნქცია, რომელიც დეკორირებულია HTTP მეთოდის დეკორატორით (`@app.get`, `@app.post` და ა.შ.), რომელიც მოამუშავებს მოთხოვნებს path-ზე. ფუნქციის დაბრუნებული მნიშვნელობა ავტომატურად სერიალიზდება 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 მეთოდს + path-ს handler-თან. ფუნქციის სახელი თქვენი არის; დეკორატორი განსაზღვრავს მარშრუტს. დაბრუნებული dict-ები/list-ები/Pydantic მოდელები ავტომატურად სერიალიზდება JSON-ში — ხელით `json.dumps` არ არის საჭირო.

## თანმიმდევრობა მნიშვნელოვანია გადაფარებული path-ების შემთხვევაში

```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 ემთხვევა მარშრუტებს დეკლარაციის თანმიმდევრობაში, ასე რომ ჯერ სტატიკური path-ები დადეთ, შემდეგ დინამიური.

## ოპერაციის მეტაדეტა (დოკუმენტაციის ამოქმედება)

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

დეკორატორის პარამეტრები (`tags`, `summary`, `status_code`, `response_model`) კონფიგურირებენ ქცევას და აუმჯობესებენ ავტომატურად გენერირებულ დოკუმენტაციას.

## რატომ არის ეს მნიშვნელოვანი

path operation-ები არის ყველა FastAPI აპლიკაციის საფუძველი — ისინი განსაზღვრავენ თქვენი API-ის endpoint-ებს და როგორ მოიპყრობა მოთხოვნებს.

დეკორატორი-თითო-HTTP-მეთოდის შაბლონის გაგება, რომ დაბრუნებული მნიშვნელობები ავტომატურად სერიალიზდება JSON-ში (არ არის boilerplate კოდი), რომ ტიპის მინიშნებები პარამეტრებზე აკეთებს კონვერსიას და ვალიდაციას, და რომ მარშრუტის თანმიმდევრობა მნიშვნელოვანია გადაფარებული path-ების შემთხვევაში, არის ყოველდღიური სიცოცხლისთვის აუცილებელი ცოდნა ნებისმიერი endpoint-ის აგებისთვის.

დეკორატორის მეტადეტა ასევე კვებავს FastAPI-ის ავტომატურ დოკუმენტაციას, მარშრუტებს პირდაპირ დოკუმენტაციასთან აკავშირებს.

ეს არის პირველი და ყველაზე ფუნდამენტური რამ, რასაც FastAPI-ში უნდა აითვისოთ.