📦 Body - Multiple Parameters

FastAPI에서 Body 파라미터는 단순히 “요청에 JSON을 담는다” 수준을 넘어서 API 설계의 구조 자체를 결정하는 요소다.

이번 글에서는 Request Body에 여러 개의 파라미터를 담는 경우, FastAPI가 이를 어떻게 해석하고 처리하는지를 단계적으로 정리한다.

📚 어원으로 시작하기

Body는 영어로 몸통을 의미한다. HTTP 요청도 사람처럼 구조를 가진다.

Parameter는 함수에 전달되는 입력값이다.

🚚 FastAPI 파라미터 전달 경로

이번 글의 핵심은 “Body 안에 여러 개의 상자를 넣으면 어떻게 될까?”이다.

🛠 실습 환경 준비

# 프로젝트 폴더 생성
mkdir fastapi-body-params
cd fastapi-body-params

# 가상환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# FastAPI 설치
pip install "fastapi[standard]"

✍️ 첫 번째 코드: Body 파라미터 1개

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {
        "item_id": item_id,
        "item": item
    }

• 클라이언트는 JSON 객체를 보내야 한다
• 필수 필드: name, price
• 선택 필드: description, tax
• 타입이 다르면 요청 단계에서 자동으로 거부됨

테스트: Swagger UI에서 해당 Request Body 입력 후 "Try it out" 클릭

{
  "name": "노트북",
  "description": "개발용 맥북",
  "price": 2500000,
  "tax": 250000
}

결과:

✔ 1. Path 파라미터 정상 수신
→ URL의 {item_id}가 정확히 매핑됨

✔ 2. Request Body가 모델로 파싱됨
→ JSON → Item 객체 → 다시 JSON

✍️ 두 번째 코드: Body 파라미터 2개로 확장

이제 Body 파라미터를 하나 더 추가해보자.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

class User(BaseModel):
    username: str
    full_name: str | None = None

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Item,
    user: User
):
    return {
        "item_id": item_id,
        "item": item,
        "user": user
    }

Swagger UI에서 확인하면 Request Body의 형태가 달라진 것을 확인할 수 있다.
변경된 Request Body구조:

{
  "item": {
    "name": "노트북",
    "description": "개발용 맥북",
    "price": 2500000,
    "tax": 250000
  },
  "user": {
    "username": "Jay",
    "full_name": "김종언"
  }
}

결과:

🧠 핵심 규칙 정리

이 동작은 옵션이 아니라 FastAPI의 기본 규칙이다.

🧠 이론과 핵심 내용

이제 “왜 FastAPI가 이렇게 동작하는지”를 구조적으로 정리해보자. 핵심은 FastAPI의 파라미터 자동 인식 규칙이다.

🔍 FastAPI 파라미터 자동 인식 규칙

FastAPI는 함수의 시그니처만 보고 각 파라미터를 어디에서 가져올지 자동으로 결정한다.

🧩 파라미터 혼합 예제

하나의 API에서 Path · Query · Body를 함께 사용하는 예제를 보자.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,        # Path
    item: Item,          # Body
    q: str | None = None # Query
):
    result = {
        "item_id": item_id,
        "item": item
    }
    if q:
        result["q"] = q
    return result

FastAPI는 다음과 같이 해석한다.

• item_id → URL에 있으므로 Path
• item → Pydantic 모델이므로 Body
• q → 단순 타입 + 기본값 → Query

📦 Body 파라미터가 여러 개일 때의 내부 동작

왜 Body 파라미터가 2개 이상이면 JSON 구조가 바뀔까?

이유는 단순하다.

Body 파라미터가 1개일 때는 모호하지 않다.

{
  "name": "노트북",
  "price": 2500000
}

하지만 Body 파라미터가 2개라면?

{
  "name": "노트북",
  "price": 2500000,
  "username": "jay"
}

이 구조에서는 어디까지가 Item이고, 어디부터 User인지 구분할 수 없다.

그래서 FastAPI는 파라미터 이름을 JSON의 키로 사용한다.

🧱 Body()로 단순 타입을 Body에 포함하기

기본적으로 int, str 같은 단순 타입은 Query 파라미터로 인식된다.

하지만 단순 값도 Body에 넣고 싶다면 Body()를 사용한다.

from fastapi import FastAPI, Body
from pydantic import BaseModel
from typing import Annotated

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Item,
    importance: Annotated[int, Body()]
):
    return {
        "item_id": item_id,
        "item": item,
        "importance": importance
    }

요청 Body는 다음과 같다.

{
  "item": {
    "name": "노트북",
    "price": 2500000
  },
  "importance": 5
}

🧩 embed 옵션: Body 하나도 감싸고 싶을 때

Body 파라미터가 1개일 때도 JSON을 키로 감싸고 싶다면 embed=True를 사용한다.

from fastapi import FastAPI, Body
from pydantic import BaseModel
from typing import Annotated

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Annotated[Item, Body(embed=True)]
):
    return {
        "item_id": item_id,
        "item": item
    }

요청 JSON 비교:

{ "name": "노트북", "price": 2500000 }

{ "item": { "name": "노트북", "price": 2500000 } }

📌 기억해야 할 포인트

• Body 파라미터 개수는 JSON 스키마를 바꾼다
• 이 변경은 FastAPI의 자동 규칙이다
• 프론트엔드와 반드시 구조를 사전에 합의해야 한다
• embed, Body() 옵션은 설계 단계에서 결정한다

🧾 최종 정리