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

🔍 발생 상황

FastAPI 프로젝트에서 Swagger UI를 사용할 때

처음에는 POST 요청 입력창이 아래처럼 나왔었다.

• text input으로 단어 입력
• select box로 타입 고르기 (general, brand)

하지만 어느 순간부터 아래처럼 바뀌었다:

• 하나의 JSON textarea만 나옴
• 전체 request body를 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/Python] - [FastAPI] 페이징, 정렬, 리스트 파라미터까지 포함한 검색 API 확장 설계

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

---

🤔 왜 UI가 바뀐 걸까?

이건 FastAPI의 Request Body 정의 방식에 따라 Swagger UI가 자동으로 바뀌기 때문이다.

FastAPI는 내부적으로 OpenAPI 스펙을 사용해서 Swagger 문서를 생성하는데,

Form 방식과 Pydantic Body 방식은 서로 다르게 인식된다.

---

✅  Form 방식: text input + select box

from fastapi import Form

@router.post("/form")
def add_exclude_word_form(
    word: str = Form(...),
    type: str = Form(...)
):
    ...

이렇게 Form(...)을 사용하면 Swagger는 이를

application/x-www-form-urlencoded 형식의 폼 요청으로 판단하고,

input 필드들을 각각 분리해서 UI에 렌더링한다.

---

✅  JSON Body 방식: textarea (JSON) 입력

from pydantic import BaseModel

class ExcludeWordCreate(BaseModel):
    word: str
    type: str

@router.post("/")
def add_exclude_word(data: ExcludeWordCreate):
    ...

이처럼 Pydantic 모델을 사용해서 body를 받는 경우,

FastAPI는 application/json 형식의 요청으로 간주한다.

그래서 Swagger에서는 JSON textarea를 보여주고,

사용자가 전체 JSON body를 직접 입력해야 하는 구조가 된다.

---

✅ 정리 요약

방식	Swagger UI 입력 형태	FastAPI 요청 방식	Content-Type
Form(...)	text input + select	form 필드로 전달	application/x-www-form-urlencoded
Pydantic(BaseModel)	JSON textarea	body 전체로 전달	application/json

---

✨ 결론

• Swagger UI는 FastAPI의 엔드포인트 정의 방식에 따라 자동으로 UI를 바꾼다
• Form()을 쓰면 input 필드로
• Pydantic 모델을 쓰면 JSON textarea로
• 두 방식 중 대부분의 실제 API 서비스에서는 JSON 방식을 사용한다

---

🧩 참고 팁

• 테스트용으로 Swagger에서 간편하게 값을 넣고 싶다면 Form(...)도 유용함
• 하지만 실제 클라이언트 앱(FE, 앱, etc)은 보통 application/json 형식으로 통신함
• 따라서 배포용 API는 대부분 JSON 구조를 사용하는 게 일반적이다