FastAPI: Query, Param, Body

FastAPI: Router 설정하기. 이후의 글.

FastAPI에서 라우터는 단순히 “URL 하나”를 만드는 수준을 넘어,
HTTP 메서드, 경로, 파라미터 타입까지 한 번에 선언할 수 있다.


이 글에서는 @router.get, @router.post를 중심으로,
Path/Query/Body 파라미터를 어떻게 선언하는지 실제 코드와 함께 정리하였다.

---

주요 라우터 데코레이터와 역할

1. @router.get – 경로 파라미터로 리소스 조회하기

• GET 요청에 사용.
• URL에 쿼리 파라미터, 경로 파라미터를 받을 수 있음.

from fastapi import APIRouter

router = APIRouter()

@router.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

/users/1요청 시 {"user_id": 1}이 반환된다.


Path parameter는 URL에 포함되는 값이고,
타입 힌트(int)에 따라 자동 변환·검증된다.

---

2. @router.post – JSON Body로 유저 생성하기

from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter()

class UserCreate(BaseModel):
    name: str
    age: int

@router.post("/users")
async def create_user(user: UserCreate):
    return {"name": user.name, "age": user.age}

• POST는 보통 Body에 데이터를 담아서 서버에 보내는 용도

• 요청 예시:

{
  "name": "Beom",
  "age": 26
}

• Pydantic 모델을 쓰면 타입 검증과 Swagger 스키마가 자동으로 생성된다.

---

3. Path / Query / Body 파라미터 정리

Path parameter

@router.get("/users/{user_id}")
async def get_user(user_id: int):
    ...

---

Query parameter

@router.get("/search")
async def search(name: str):
    return {"name": name}
# /search?name=foo

---

Body

@router.post("/users")
async def create_user(user: UserCreate):
    ...

---

세 가지 동시에 사용

• 하나의 엔드포인트에서 Path + Query + Body를 동시에 쓸 수 있다.
  • 예시:

@router.put("/users/{user_id}")
async def update_user(user_id: int, active: bool, body: UserCreate):
    ...
# /users/1?active=true

---

4. 기타 메서드 + Swagger 연계

• 마지막으로, PUT/DELETE도 문법은 같다

@router.put("/users/{user_id}")
@router.delete("/users/{user_id}")

---

마무리

이번 글에서는 FastAPI에서 가장 자주 쓰는
@router.get, @router.post와 Path/Query/Body 파라미터를 살펴봤다.


다음글로는 'Fastapi: XGBRegressor를 이용'을 작성하도록 하겠다.

---

Reference:

#3. Fastapi로 모델 서빙부터 DevOps 까지 : Query, Param, Body