경로 매개변수 (Path Parameters)

{param} 타입 변환 Enum Path 순서

URL 경로의 일부를 함수 인자로 받습니다. 타입을 선언하면 자동 변환·검증됩니다.

1. 기본

@app.get("/items/{item_id}")
def read_item(item_id: int):     # "/items/3" -> item_id == 3 (int)
    return {"item_id": item_id}

# "/items/abc" -> 422 Unprocessable Entity (자동 검증 에러)

2. 경로 우선순위

@app.get("/users/me")        # 먼저 선언 -> 고정 경로 우선
def read_me():
    return {"user": "current"}

@app.get("/users/{user_id}") # 나중 선언
def read_user(user_id: int):
    return {"user_id": user_id}

주의

순서가 바뀌면 /users/me 요청이 {user_id} 로 잡혀 me 를 int 변환하려다 422

3. Enum 으로 허용값 제한

from enum import Enum

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"

@app.get("/models/{name}")
def get_model(name: ModelName):
    return {"model": name.value}

# 허용값이 OpenAPI 스키마·/docs 드롭다운에 반영됨

4. 경로에 슬래시 포함 (path 컨버터)

@app.get("/files/{file_path:path}")
def read_file(file_path: str):
    # "/files/home/ubuntu/a.txt" -> file_path == "home/ubuntu/a.txt"
    return {"path": file_path}

5. Path() 로 제약 추가

from typing import Annotated
from fastapi import Path

@app.get("/items/{item_id}")
def read_item(
    item_id: Annotated[int, Path(title="아이템 ID", ge=1, le=1000)],
):
    return {"item_id": item_id}

"느린 것은 async 로, 무거운 것은 백그라운드로"