API 문서
본 문서는 MARU 의 API 명세서 입니다.
프로젝트명: MARU
작성일: 2026-01-20
최종 수정일: 2026-02-19
수정 이력
| 수정일 | 수정 내용 |
|---|---|
| 2026-01-20 | API 문서 초안 작성 |
| 2026-02-16 | 누락된 API Contract 항목 추가 |
| 2026-02-19 | 프론트엔드 API 통합 패턴 섹션 추가 |
- 프로젝트의 API 문서는 Swagger UI와 API Contracts Markdown 문서를 제공합니다.
- Swagger UI는 API 테스트 및 인증 토큰을 발급한 상태로 모의 테스트가 가능합니다.
- API Contracts 문서는 상세 명세 및 예시가 제공됩니다.
| 환경 | URL |
|---|---|
| Production | MARU API 문서 |
| 기능 | 설명 |
|---|---|
| API 테스트 | 브라우저에서 직접 API 호출이 가능합니다. |
| 편의 도구 지원 | 개발 도구를 지원합니다. 데모 인증 및 ID 복사가 가능합니다. |
| 인증 지원 | 데모 로그인 버튼으로 즉시 데모 계정 인증 및 토큰 발급이 가능합니다. |
| ID 복사 | 개발도구로 응답에서 추출된 ID를 볼 수 있습니다. 클릭 시 클립보드로 복사합니다. |
Swagger UI에서 데모 계정으로 로그인 버튼 클릭 시:
- 소셜 로그인 없이 즉시 인증이 가능합니다.
- 테스트용 도장/원생 데이터에 접근이 가능합니다.
- 데모 계정은 데이터 보호를 위해 DELETE 요청과 SMS 발송이 차단됩니다. API 응답은 정상적으로 표시되지만 실제로 처리되지 않습니다.
| 파일 | 도메인 | 주요 엔드포인트 |
|---|---|---|
| auth | 인증 | /api/v1/auth/** |
| users | 사용자 | /api/v1/users/** |
| students | 원생 | /api/v1/students/** |
| divisions | 수업 편성 | /api/v1/divisions/** |
| sections | 수련부 관리 | /api/v1/sections/** |
| enrollments | 수강 등록 | /api/v1/enrollments/** |
| attendance | 출결 | /api/v1/attendance/** |
| payments | 수납 | /api/v1/payments/** |
| notifications | 알림/발송 현황 | /api/v1/notifications/** |
| messages | 메시지 | /api/v1/messages/** |
| broadcasts | 일괄 발송 | /api/v1/broadcasts/** |
| employments | 사범 고용 관리 | /api/v1/employments/** |
| dojangs | 도장 관리 | /api/v1/dojangs/** |
| sms | SMS 인증 | /api/v1/sms/** |
| sub-merchants | 하위가맹점 | /api/v1/sub-merchants/** |
| refunds | 환불 | /api/v1/payments/{paymentId}/refunds |
| payment-links | 결제 링크 | /api/v1/pay/** |
| pg-payments | PG 결제 | /api/v1/invoices/**/payment-links |
| permissions | 권한 | 역할 기반 접근 제어 |
| dashboard | 대시보드 | /api/v1/dashboard/** |
각 Contract 문서는 다음 형식으로 작성되어 있습니다 :
## API 엔드포인트
### POST /api/v1/example
설명: ...
#### Request
- Headers: ...
- Body: ...
#### Response
- 200 OK: ...
- 400 Bad Request: ...frontend/src/services/api.ts # axios 인스턴스 및 interceptor
frontend/src/services/*Service.ts # 도메인별 API 서비스
frontend/src/services/*Api.ts # 도메인별 API 서비스
api.ts에서 생성된 apiClient를 모든 서비스에서 공유합니다.
| 설정 | 값 | 설명 |
|---|---|---|
baseURL |
import.meta.env.VITE_API_BASE_URL |
환경 변수에서 API 기본 URL 로드 |
Content-Type |
application/json |
기본 요청 헤더 |
timeout |
10000 (10초) |
요청 타임아웃 |
withCredentials |
true |
httpOnly Cookie 기반 인증을 위해 쿠키 자동 전송 |
JWT 토큰은 서버에서 httpOnly Cookie로 관리됩니다. 프론트엔드에서 직접 토큰을 다루지 않으며, withCredentials: true 설정으로 브라우저가 요청마다 쿠키를 자동 전송합니다.
응답 interceptor에서 HTTP 상태 코드에 따라 전역 에러 처리를 수행합니다.
| 상태 코드 | 처리 |
|---|---|
| 401 Unauthorized | SweetAlert2로 세션 만료 알림 → 확인 시 /login으로 이동 |
| 403 Forbidden (AUTH_ 에러 또는 에러 코드 없음) | SweetAlert2로 세션 만료 알림 → 확인 시 /login으로 이동 |
| 403 Forbidden (권한 에러) | SweetAlert2로 권한 변경 알림 → 확인 시 /dashboard로 이동 |
| 기타 |
Promise.reject(error)로 개별 호출부에서 처리 |
401, 403 처리 시
return new Promise(() => {})패턴으로 후속.catch()실행을 차단합니다.
// 정상 응답
interface ApiResponse<T> {
data: T;
message?: string;
}
// 에러 응답
interface ErrorResponse {
timestamp: string;
status: number;
error: string;
code: string;
message: string;
path?: string;
}| 파일 | 도메인 |
|---|---|
authService.ts |
인증 (로그인, 로그아웃, 도장 선택) |
userService.ts |
사용자 (프로필, 도장 목록) |
studentService.ts |
원생 관리 |
attendanceService.ts |
출결 관리 |
dashboardService.ts |
대시보드 |
dojangService.ts |
도장 관리 |
divisionApi.ts |
수업 편성 |
sectionApi.ts |
수련부 관리 |
invoiceApi.ts |
청구서 관리 |
broadcastApi.ts |
일괄 발송 |
notificationApi.ts |
알림 관리 |
employmentService.ts |
사범 고용 관리 |
smsService.ts |
SMS 인증 |
paymentPageApi.ts |
결제 페이지 |