챕터 3.5: Swagger 자동 문서화
학습 시간: 30분
1. API 문서화: 우주 정거장 사용 설명서
당신이 ISS에 새로 온 우주 비행사라고 상상해 보세요. 어떤 스위치가 무엇을 제어하는지, 로봇 팔을 어떻게 조작하는지 어떻게 알 수 있을까요? 자세하고 최신 상태의 설명서가 필요합니다.
API 문서화는 개발자에게 이러한 설명서와 같습니다. 다음을 설명합니다:
- 어떤 "도킹 포트"(엔드포인트)를 사용할 수 있는지.
- 어떤 "명령"(HTTP 메서드)을 보낼 수 있는지.
- 어떤 "화물"(데이터)을 전송해야 하는지.
- 어떤 "텔레메트리"(응답)를 기대해야 하는지.
문제는 문서를 수동으로 작성하는 것은 시간이 오래 걸리고, 지루하며, 거의 항상 구식이 된다는 것입니다.
💡 우주 비유:
수동 문서는 스테이션을 현대화한 후에도 업데이트되지 않고 아카이브에 보관되는 종이 도면과 같습니다. FastAPI의 자동 문서화는 스테이션의 모든 변경 사항에 따라 실시간으로 업데이트되는 관제 센터(MCC)의 대화형 디스플레이입니다.
2. FastAPI의 마법: 작동 방식
FastAPI는 당신의 코드에 기반하여 모든 "힘든 작업"을 대신 처리합니다. 다음을 스캔합니다:
- 경로: 모든
@app.get,@app.post등의 데코레이터. - 매개변수: 경로 매개변수 (
ship_id: int) 및 쿼리 매개변수. - Pydantic 모델: 당신의 "설계도" (
Spaceship,SpaceshipCreate). - 문서 문자열(docstrings): 세 개의 따옴표로 작성한 설명.
이러한 데이터를 기반으로 FastAPI는 OpenAPI (이전 Swagger로 알려짐) 표준에 따라 스키마를 생성한 다음, 두 가지 아름다운 인터페이스를 통해 이를 보여줍니다.
3. "관제 센터(MCC) 디스플레이" 탐색: Swagger UI
Swagger UI는 문서를 읽을 수 있을 뿐만 아니라 브라우저에서 직접 API를 테스트할 수 있는 대화형 인터페이스입니다.
http://127.0.0.1:8000/docs를 엽니다.
다음과 같은 내용이 표시됩니다:
- 엔드포인트 목록: 태그별(기본적으로 리소스 이름별)로 그룹화되어 있으며 HTTP 메서드 색상으로 표시됩니다.
- 설명: docstrings (
"""...""")의 텍스트가 엔드포인트 설명으로 표시됩니다. - 매개변수: 엔드포인트가 예상하는 매개변수(예:
ship_id), 해당 유형 및 필수 여부를 보여줍니다. - 요청 본문(Request Body):
POST및PUT의 경우 Pydantic 모델(SpaceshipCreate)에서 생성된 JSON 스키마를 보여줍니다. - 응답(Responses): 가능한 상태 코드 및
response_model에 기반한 응답 스키마를 보여줍니다. - "Try it out" 버튼: 매개변수를 채우고 서버에 실제 요청을 보낼 수 있습니다.
4. 문서화 개선: 태그 및 설명
이제 문서화를 더욱 전문적으로 만들어 봅시다.
단계 1: FastAPI에 메타데이터 추가
app을 생성할 때 API에 대한 일반 정보를 전달할 수 있습니다.
main.py의 app = FastAPI() 줄을 변경합니다:
단계 2: 태그를 사용하여 엔드포인트 그룹화 각 엔드포인트에 태그를 추가하여 의미별로 그룹화할 수 있습니다.
데코레이터에 tags 매개변수를 추가합니다:
# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["우주선"])
# ...
# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["우주선"])
# ...
# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["우주선"])
# ...
# 및 PUT과 DELETE에 대해서도 마찬가지
5. 대안적인 보기: ReDoc
FastAPI는 "기본적으로" 또 다른 문서 인터페이스인 ReDoc을 제공합니다. 이는 상호 작용이 적지만, 더 읽기 쉽다고 여겨지며 정적 문서에 매우 적합합니다.
http://127.0.0.1:8000/redoc를 엽니다.
탐색, 엔드포인트 설명 및 데이터 스키마가 있는 3열 레이아웃이 표시됩니다. 이는 "클라이언트"(예: 프론트엔드 팀)에게 문서를 제공하는 훌륭한 방법입니다.
복습 퀴즈
🚀 챕터 요약:
FastAPI의 가장 강력한 기능 중 하나인 노력 없이 문서를 생성하는 방법을 살펴보았습니다.
- 📖 이제 API에 Swagger UI와 ReDoc이라는 두 가지 최신 문서가 있습니다.
- 🔬 문서는 대화형이며 즉석에서 API를 테스트할 수 있습니다.
- 🏷️ 메타데이터와 태그를 사용하여 문서를 개선하는 방법을 배웠습니다.
사용 설명서가 준비되었고 항상 최신 상태입니다! 이 섹션의 마지막 챕터에서는 "우주 이상 현상", 즉 오류 및 잘못된 데이터를 처리하는 방법을 배웁니다.
📌 확인 사항:
http://127.0.0.1:8000/docs주소에 제목, 설명 및 태그별로 그룹화된 엔드포인트가 표시되는지 확인합니다.- "Schemas" 섹션에
Spaceship모델이 보이는지 확인합니다.http://127.0.0.1:8000/redoc을 열고 대체 보기를 평가합니다.⚠️ 변경 사항이 표시되지 않는 경우: - 파일
main.py를 저장했는지 확인하세요. -uvicorn서버가--reload플래그로 실행 중이며 성공적으로 재시작되었는지 확인하세요.