[FastAPI] 페이징, 정렬, 리스트 파라미터까지 포함한 검색 API 확장 설계

서론

기능 확장

기본적인 다중 필터 API에서 아래 기능을 추가하고 싶다:

• 페이지네이션 (page, size)
• 정렬 (sort_by, order)
• 복수 브랜드 선택 (brands=apple&brands=samsung)

---

전체 API 예시

GET /products?brands=apple&brands=samsung&category=전자기기&sort_by=price&order=desc&page=1&size=10

---

본론

라우터 정의

from fastapi import APIRouter, Query
from typing import List, Optional
from enum import Enum

router = APIRouter()

class SortOrder(str, Enum):
    asc = "asc"
    desc = "desc"

@router.get("/products")
def filter_products(
    brands: Optional[List[str]] = Query(None),
    category: Optional[str] = None,
    sort_by: Optional[str] = "created_at",
    order: SortOrder = SortOrder.desc,
    page: int = 1,
    size: int = 10
):
    ...

---

SQLAlchemy에서 동적 쿼리 구성

from sqlalchemy import asc, desc
from sqlalchemy.orm import Session
from app.models import Product

def get_filtered_products(
    db: Session,
    brands: Optional[List[str]],
    category: Optional[str],
    sort_by: str,
    order: SortOrder,
    page: int,
    size: int
):
    query = db.query(Product)

    if brands:
        query = query.filter(Product.brand.in_(brands))
    if category:
        query = query.filter(Product.category == category)

    # 정렬 처리
    sort_column = getattr(Product, sort_by, None)
    if sort_column is not None:
        query = query.order_by(desc(sort_column) if order == "desc" else asc(sort_column))

    # 페이징 처리
    offset = (page - 1) * size
    query = query.offset(offset).limit(size)

    return query.all()

---

Swagger UI 자동화

FastAPI는 Enum(SortOrder)이나 List, Default 값을 기반으로

Swagger UI에서 select box, multiple 입력 등을 자동으로 지원해줌.

---

호출 예시

GET /products?brands=apple&brands=samsung&category=노트북&sort_by=price&order=asc&page=2&size=5

• 브랜드: apple 또는 samsung
• 카테고리: 노트북
• 가격 기준 오름차순
• 2페이지 (5개씩)

---

정리 요약

기능	구현 방식
다중 필터링	List[str] + Optional[str]
정렬 처리	sort_by + order 쌍 사용
페이징 처리	page, size → offset/limit 계산

---

결론

• 실무 API에서는 페이징/정렬/다중 필터가 거의 필수
• FastAPI + SQLAlchemy 조합으로 이 모든 걸 쉽게 구현 가능
• Swagger에서도 훌륭한 자동화 UI 제공됨
• 클라이언트 입장에서도 예측 가능하고 유연한 API 구조가 됨

 

🔗 엮인글

[🚀 Dev/Python] - [FastAPI] Swagger UI에서 POST 요청 시 JSON 입력창으로 바뀌는 이유

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 JSON이 아닌 Path Param으로 값 전달하는 방법

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 path param 여러 개 받는 방법

[🚀 Dev/Python] - [FastAPI] 쿼리 파라미터 vs path 파라미터 설계 전략

[🚀 Dev/Python] - [FastAPI] 다중 필터 검색 API 설계 (예: /products?brand=..&category=..)

[🚀 Dev/Nextjs] - [Nextjs] 필터 UI → FastAPI 다중 필터 API 연결 가이드

---