📝 가계부 API (OpenAPI 3.0.3) 시각적 구조 요약 API 상세 명세서

📝 가계부 API (OpenAPI 3.0.3) 시각적 구조 요약

---

1️⃣ 기본 정보

• API 명: 가계부 API
• 버전: 1.0.0
• 설명: Django REST Framework 기반 가계부 관리 API

---

2️⃣ 메인 엔드포인트 구조

📦 [accounts] 계좌 관련

메서드경로설명

GET	/api/accounts/	계좌 목록 조회
POST	/api/accounts/	새 계좌 생성
GET	/api/accounts/{account_id}/	특정 계좌 상세 조회
DELETE	/api/accounts/{account_id}/	특정 계좌 삭제

 

---

💸 [transactions] 거래내역 관련

메서드경로설명

GET	/api/accounts/{account_id}/transactions/	거래내역 목록 조회
POST	/api/accounts/{account_id}/transactions/	거래내역 생성
GET	/api/accounts/{account_id}/transactions/{id}/	거래내역 상세 조회
PUT	/api/accounts/{account_id}/transactions/{id}/	거래내역 수정(전체)
PATCH	/api/accounts/{account_id}/transactions/{id}/	거래내역 수정(부분)
DELETE	/api/accounts/{account_id}/transactions/{id}/	거래내역 삭제

 

---

🧑‍💻 [auth] 인증 관련

메서드경로설명

POST	/api/auth/login/	로그인(JWT 쿠키 발급)
POST	/api/auth/logout/	로그아웃(쿠키 삭제)
POST	/api/auth/signup/	회원가입
POST	/api/auth/token/	토큰 발급(일반)
POST	/api/auth/token/refresh/	리프레시 토큰으로 재발급
GET	/api/auth/activate/{uidb64}/{token}/	이메일 인증

 

---

🙋 [users] 내 정보

메서드경로설명

GET	/api/users/me/	내 정보 조회
PATCH	/api/users/me/	내 정보 수정
DELETE	/api/users/me/	회원 탈퇴

 

---

🌏 [oauth] 소셜 로그인/닉네임

메서드경로설명

POST	/oauth/check-nickname/	닉네임 중복확인 (POST)
GET	/oauth/nickname/check/	닉네임 중복확인 (GET)
POST	/oauth/nickname/	닉네임 설정(OAuth)

 

---

3️⃣ 응답/요청 예시

• 모든 엔드포인트는 상태 코드별 응답/실패/예시를 포함
• 대부분 JWT 인증 필요(bearerAuth/쿠키 방식)
• 계좌 생성/조회, 거래내역, 회원가입, 로그인 등 실전 실습/프론트 연동 가능

---

4️⃣ Swagger 문서 활용법

• 실제 문서는 /swagger/ 혹은 /docs/에서 실시간 확인 + 테스트 가능
• 각 엔드포인트 클릭 → 요청/응답/필수 파라미터, 예시 등 자동 표기
• 요청/응답 스키마(예시)

{
  "account_number": "123-456-7890",
  "bank_code": "004",
  "account_type": "SAVING"
}

• 필수/옵션 파라미터, 입력값, 반환값, 예외처리가 명확히 나옴

---

5️⃣ 주요 Schema(모델/데이터 구조)

• Account, TransactionHistory, User, SignupRequest 등
• Enum/선택값(은행코드, 거래타입 등)도 모두 문서에 포함

---

6️⃣ 실무 TIP/체크포인트

• Swagger UI/문서만 공유해도 프론트와 “실시간” 협업 가능
• 추가 설명/예시/오류케이스 등은 @extend_schema, description 등으로 확장
• 실제 배포 시에는 /swagger/ 같은 엔드포인트를 개발 전용(비공개)로 운영 추천

---

🟩 결론

• 이 OpenAPI YAML → Swagger UI로 바로 변환되어
  브라우저에서 시각화/테스트/협업에 최적화됨
• API 설계→문서→테스트→협업 전 과정이 자동화되어
  실무에서 매우 중요한 역할을 함