웹 기반 사용자 인터페이스(UI), Swagger

웹 기반 사용자 인터페이스(UI), Swagger

FastAPI에서 제공하는 Swagger는 API 문서를 자동으로 생성해 주는 웹 기반 사용자 인터페이스(UI)입니다.
API를 설명하고, 직접 테스트까지 할 수 있는 편리한 도구입니다.

---

✅ Swagger란?

• 웹 API의 기능을 시각적으로 보여주는 도구
• API 요청 방법과 응답 구조를 자동으로 문서화
• 직접 버튼 클릭으로 요청을 보내고 결과를 확인할 수 있음
• FastAPI는 Swagger를 내장하여 별도 설정 없이 /docs 주소에서 바로 제공

---

📌 Swagger의 주요 기능

기능 설명

API 목록 보기	모든 경로(GET, POST 등)를 한눈에 확인 가능
입력 필드 자동 생성	필요한 데이터 형식을 자동으로 표시
버튼 클릭 테스트	코드 작성 없이 API 실행 가능
응답 확인	응답 데이터의 형태와 상태 코드 확인 가능
스키마 문서화	BaseModel로 정의한 데이터 구조를 자동 문서로 표시

---

🖥️ 접속 방법

FastAPI 서버가 실행 중일 때, 아래 주소로 접속하면 됩니다:

http://<서버 IP>:8000/docs

예:

http://192.168.142.200:8000/docs

---

📸 예시 화면

구분 설명

/greet/{name}	문자열을 입력하면 인사 메시지 반환
/calculate?x=2&y=3	숫자 두 개를 입력하면 더한 결과 반환
/signup (POST)	JSON 형식으로 사용자 등록 요청 가능

---

💬 Swagger와 Redoc 차이점

항목 Swagger (/docs) Redoc (/redoc)

특징	기능 중심, 실시간 테스트 가능	문서 중심, 정리된 느낌
UI	간단하고 직관적	세련되고 읽기 좋음
추천 용도	개발자 테스트용	사용자 매뉴얼용

 

 

Swagger

Redoc

---

✅ 왜 중요한가요?

• 개발자와 디자이너가 소통할 때 API 설명서를 대신함
• 클라이언트(앱, 웹 개발자)가 서버 기능을 테스트할 수 있음
• 오류가 날 경우 어디서 잘못됐는지 쉽게 파악 가능
• 개발 후 문서를 따로 만들 필요 없음 → 자동 생성

---

🔚 정리

Swagger는 FastAPI가 만들어주는 'API 사용 설명서 + 체험 공간'입니다.

📦 "이 API는 무엇을 하고, 어떻게 써야 하는지"를 알려주는 스마트 설명서라고 보시면 됩니다.

---

필요하시면 Swagger 기능을 확장해서 로그인 API, 토큰 인증, 파일 업로드 같은 예제도 만들어드릴 수 있습니다.
Swagger로 만들어보고 싶은 항목 있으시면 알려주세요!