백엔드 기초집: Python FastAPILESSON 09

API 문서 Swagger UI와 ReDoc

난이도초급

예상 시간35분

선수지식이전 강의

9강. API 문서 Swagger UI와 ReDoc

1. 이번 강의에서 해결할 문제

endpoint가 늘어나면 프론트엔드 개발자가 요청 형식을 추측해야 합니다. 코드에서 자동 생성되는 문서를 실제 협업 계약으로 정리합니다.

2. 학습 목표

3. 핵심 개념

FastAPI는 타입과 path operation 정보로 /openapi.json을 만들고 /docs의 Swagger UI와 /redoc의 ReDoc이 이를 렌더링합니다. 문서는 실제 코드에서 생성되므로 별도 문서보다 덜 쉽게 낡지만, 설명과 예시는 개발자가 의도적으로 작성해야 합니다.

4. 단계별 코드 예시

파일 경로: game-ranking-api/app/schemas.py

app/schemas.py
from pydantic import BaseModel, ConfigDict, Field


class RecordCreate(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={"examples": [{"game_name": "Rule Break", "score": 1200}]}
    )

    game_name: str = Field(min_length=1, max_length=80, description="게임 표시 이름")
    score: int = Field(ge=0, le=1_000_000, description="획득 점수")

파일 경로: game-ranking-api/app/main.py

app/main.py
from fastapi import FastAPI, status

from app.schemas import RecordCreate

tags_metadata = [
    {"name": "records", "description": "사용자의 게임 플레이 기록"},
    {"name": "rankings", "description": "게임별 최고 점수 집계"},
]

app = FastAPI(
    title="Game Ranking API",
    version="0.1.0",
    description="게임 기록을 저장하고 랭킹을 조회하는 REST API",
    openapi_tags=tags_metadata,
)


@app.post(
    "/records",
    tags=["records"],
    summary="게임 기록 생성",
    status_code=status.HTTP_201_CREATED,
)
def create_record(payload: RecordCreate) -> dict[str, object]:
    """검증된 게임 이름과 점수로 새 기록을 만듭니다."""
    return {"id": 1, **payload.model_dump()}

실행 위치: game-ranking-api/

python -m uvicorn app.main:app --reload
Start-Process http://127.0.0.1:8000/docs
Start-Process http://127.0.0.1:8000/redoc
Invoke-RestMethod http://127.0.0.1:8000/openapi.json | ConvertTo-Json -Depth 5

5. 코드가 동작하는 이유

Pydantic이 JSON Schema를, FastAPI가 path와 응답 정보를 OpenAPI로 합칩니다. 두 UI는 같은 /openapi.json을 읽으므로 설명과 예시를 한 번 수정하면 함께 바뀝니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ