개발/FastAPI

FastAPI 시리즈 5화 - Swagger UI와 ReDoc: 자동 문서화의 힘

B컷개발자 2025. 5. 4. 11:42

FastAPI는 Swagger UI와 ReDoc을 기본으로 제공해 API 문서를 자동으로 생성합니다. 본 글에서는 그 구조와 실무 활용법을 정리해 API 문서화 효율을 극대화합니다.

 

 

개발자들이 FastAPI를 선택한 진짜 이유?

 

FastAPI는 “문서화의 고통”을 자동화합니다.

대다수 웹 프레임워크에서 API 문서는 개발자의 추가 작업이 필요하지만,

FastAPI는 OpenAPI 3.0 스펙에 맞춘 API 명세를 자동 생성합니다.

 

그 결과물로 바로 확인할 수 있는 두 가지 강력한 UI가 바로 Swagger UI와 ReDoc입니다.

 

 

1. Swagger UI – 인터랙티브한 테스트 콘솔

 

 

📌 접속 경로

 

기본 URL에서 /docs로 접속

예: http://localhost:8000/docs

 

 

📌 주요 기능

 

  • 전체 API 라우팅 목록 자동 생성
  • 각 엔드포인트의 요청/응답 스키마 명시
  • Try it out 기능을 통해 바로 테스트 가능
  • 요청/응답 예시(JSON) 자동 생성

 

 

✅ 실전에서 왜 유용한가?

 

  • 백엔드 개발자가 만든 API를 프론트엔드 개발자가 바로 확인하고 테스트할 수 있음
  • 외부에 오픈 API 제공 시 문서 따로 작성할 필요 없이 즉시 활용 가능
  • QA, 기획자, PM까지 모두 동일 문서를 기준으로 협업 가능

 

 

2. ReDoc – 깔끔하고 정돈된 문서 뷰어

 

 

📌 접속 경로

 

기본 URL에서 /redoc로 접속

예: http://localhost:8000/redoc

 

 

📌 특징

 

  • Swagger보다 정적 문서에 가까운 뷰
  • 좌측 메뉴 - 우측 상세 구조로 깔끔하게 정리
  • 복잡한 스키마 구조도 트리 형태로 시각화

 

 

✅ 사용 시점

 

  • 외부 공개용 문서로 적합
  • 회사 내부 Wiki나 Notion에 문서 임베드할 때 유리
  • 명세에 집중한 레퍼런스 자료로 활용 가능

 

 

3. FastAPI 내부에서 어떻게 작동하나?

 

FastAPI는 앱 실행 시, 내부적으로 **OpenAPI 스펙(JSON)**을 생성합니다.

 

Swagger UI와 ReDoc은 이 JSON 스펙을 기반으로 화면을 구성합니다.

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="This is my test API with automatic docs",
    version="1.0.0"
)

 

👉 옵션 구성

옵션설명

title 문서 제목
description 문서 상단 설명
version API 버전 명시
docs_url Swagger UI 접속 경로 변경 가능
redoc_url ReDoc 접속 경로 변경 가능

예: Swagger UI를 /swagger로 변경하고 싶다면?

app = FastAPI(docs_url="/swagger", redoc_url=None)

 

 

 

4. 응답/요청 예시 자동 생성 구조

 

FastAPI는 라우터에 타입 힌트와 Pydantic 모델이 포함되어 있으면

그 구조를 기반으로 자동 문서화합니다.

from pydantic import BaseModel

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

@app.post("/items", response_model=Item)
def create_item(item: Item):
    return item

이런 식으로 타입 기반으로 정의하면 다음이 자동 구성됩니다:

 

  • 요청 바디 구조
  • 필수 필드 여부
  • 응답 필드 설명
  • 에러 응답 구조 (422 오류 예시 포함)

 

 

5. 실무 활용 팁

 

  • API 개발 초기에 문서화까지 끝냄 → QA/디자인/프론트 모두 병렬 개발 가능
  • 내부 협업 시 Swagger 공유만으로 API 테스트 가능
  • 외부 클라이언트에게 제공할 경우, ReDoc 버전을 따로 정리하여 배포 가능

 

 

요약: API 문서 자동화는 단순한 편의 기능이 아니다

항목Swagger UIReDoc

형태 테스트 중심, 동적 문서 중심, 정적
접속 /docs /redoc
특징 Try it out 기능, 개발자 친화적 깔끔한 문서 보기, 외부 공개에 적합
커스터마이징 일부 가능 (로고/테마 등) 정적 HTML 추출 가능 (ReDoc CLI 활용 시)

 

 

 

다음 글 예고

 

FastAPI 시리즈 6화 - Path, Query, Header, Cookie 파라미터 제대로 다루기

에서는 API 경로 변수, 쿼리 스트링, 헤더, 쿠키 값까지 다양한 요청 파라미터를 처리하는

FastAPI의 강력한 데이터 매핑 기능을 실제 예제와 함께 소개합니다.