🚀 FastAPI 문서 시스템 개요
FastAPI는 API 문서화를 자동으로 제공하는 기능을 포함하고 있습니다. 기본 설정에서 /docs는 Swagger UI, /redoc은 ReDoc, /openapi.json은 OpenAPI 스키마를 제공합니다. 요청을 직접 시험하려면 Swagger UI를, API 구조를 읽으려면 ReDoc을 사용할 수 있습니다.
📖 FastAPI에서 제공하는 문서화 도구
FastAPI는 기본적으로 다음과 같은 문서화 도구를 제공합니다. 하나하나 살펴보겠습니다!
🎨 Swagger UI (/docs)
- FastAPI의 기본 문서화 인터페이스이자, API를 편하게 테스트할 수 있는 친구입니다.
- 버튼 클릭 몇 번으로 GET, POST 요청을 바로 날려볼 수 있습니다!
docs_url설정을 통해 원하는 경로로 변경 가능!
📜 ReDoc (/redoc)
- 보기 좋고 정리된 API 문서를 원한다면? ReDoc을 선택하세요!
- 깔끔한 디자인과 UX 덕분에 눈이 편안해집니다. 🌿
- 하지만 직접 API 요청 테스트는 불가능합니다.
🔍 OpenAPI 스펙 (/openapi.json)
- API 구조를 JSON 형식으로 확인할 수 있는 URL입니다.
- '자동 API 클라이언트 생성'이라는 강력한 기능을 지원합니다.
- UI가 없어서 심심할 수 있지만, 백엔드 개발자에게는 보물 같은 존재! 🏆
🆚 문서화 도구 비교
| 기능 | Swagger UI (/docs) | ReDoc (/redoc) | OpenAPI JSON (/openapi.json) |
|---|---|---|---|
| UI 제공 여부 | ✅ | ✅ | ❌ |
| API 테스트 | ✅ | ❌ | ❌ |
| 가독성 | 중간 | 높음 | 낮음 |
| 설정 가능 여부 | ✅ | ✅ | ✅ |
🔧 FastAPI 문서 시스템 설정하는 법
FastAPI의 문서 시스템은 아주 간단한 코드 몇 줄로 원하는 대로 설정할 수 있습니다! 🎯
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
app = FastAPI(
docs_url="/api-docs",
redoc_url="/api-redoc",
openapi_url="/api-openapi.json"
)
# 데이터 저장소 역할을 하는 임시 딕셔너리
items = {}
# Pydantic 모델 정의
class Item(BaseModel):
name: str
description: str | None = None
price: float
quantity: int
@app.get("/", tags=["Root"])
def read_root():
return {"message": "Welcome to FastAPI Sample!"}
# 모든 아이템 조회
@app.get("/items", response_model=List[Item], tags=["Items"])
def get_items():
return list(items.values())
# 특정 아이템 조회
@app.get("/items/{item_id}", response_model=Item, tags=["Items"])
def get_item(item_id: int):
if item_id not in items:
raise HTTPException(status_code=404, detail="Item not found")
return items[item_id]
# 새 아이템 생성
@app.post("/items/{item_id}", response_model=Item, tags=["Items"])
def create_item(item_id: int, item: Item):
if item_id in items:
raise HTTPException(status_code=400, detail="Item already exists")
items[item_id] = item
return item
# 아이템 업데이트
@app.put("/items/{item_id}", response_model=Item, tags=["Items"])
def update_item(item_id: int, item: Item):
if item_id not in items:
raise HTTPException(status_code=404, detail="Item not found")
items[item_id] = item
return item
# 아이템 삭제
@app.delete("/items/{item_id}", tags=["Items"])
def delete_item(item_id: int):
if item_id not in items:
raise HTTPException(status_code=404, detail="Item not found")
del items[item_id]
return {"message": "Item deleted"}
이제 /docs, /redoc, /openapi.json 대신 원하는 URL에서 API 문서를 확인할 수 있습니다! 🎉 추가적인 설정을 한다면 /api-docs, /api-redoc, /api-openapi.json 경로로 접속할 수 있습니다.
문서 비활성화와 404 점검
문서 UI만 숨기려면 다음과 같이 설정합니다.
app = FastAPI(docs_url=None, redoc_url=None)
OpenAPI 스키마까지 끄려면 openapi_url=None을 지정합니다. 스키마를 끄면 이를 사용하는 기본 문서 UI도 비활성화됩니다. 문서를 숨기는 것은 API 인증이나 접근 제한을 대신하지 않습니다. FastAPI 문서 설정 안내
문서 페이지가 404라면 다음 순서로 확인하세요.
docs_url,redoc_url,openapi_url이 기본 경로에서 변경되었는지 확인합니다.- 현재 실행 중인 앱이 설정을 수정한
app인지 확인합니다. - 프록시나 하위 경로 배포를 사용한다면 외부 주소와 앱 경로 구성을 확인합니다.
- 문서 UI가 열리지만 스키마를 가져오지 못하면 브라우저에서 OpenAPI 요청 주소와 응답을 확인합니다.
앱 실행 방식은 FastAPI·Starlette·Uvicorn 역할 설명을 참고하세요.
✨ 결론
FastAPI의 문서화 도구들은 API 개발을 한층 더 편하게 만들어 줍니다. 🚀
- Swagger UI는 테스트하기 편하고,
- ReDoc은 보기 좋으며,
- OpenAPI JSON은 개발자들이 환호하는 기능을 제공합니다.
여러분의 프로젝트에 맞는 문서화 도구를 선택해서 활용하세요! Happy coding! 😆