API Guide

API Guide

기본 정보

• Base Path: /api/v1
• Swagger UI: /swagger-ui/index.html
• OpenAPI JSON: /v3/api-docs
• Health Check: GET /api/v1/health

Swagger는 local, dev Profile에서 활성화되고 test Profile에서는 비활성화됩니다.

공통 성공 응답

{
  "resultType": "SUCCESS",
  "success": {
    "data": {}
  },
  "error": null,
  "meta": {
    "timestamp": "2026-08-13T05:00:00",
    "path": "/api/v1/example"
  }
}

공통 실패 응답

{
  "resultType": "FAIL",
  "success": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "잘못된 요청입니다.",
    "details": null
  },
  "meta": {
    "timestamp": "2026-08-13T05:00:00",
    "path": "/api/v1/example"
  }
}

응답 시간은 UTC를 기준으로 생성합니다.

Health Check 예시

GET /api/v1/health

{
  "resultType": "SUCCESS",
  "success": {
    "data": {
      "status": "UP",
      "checkedAt": "2026-08-13T05:00:00"
    }
  },
  "error": null,
  "meta": {
    "timestamp": "2026-08-13T05:00:00",
    "path": "/api/v1/health"
  }
}

API 작성 규칙

• 리소스 중심 URL과 HTTP Method를 사용합니다.
• 입력 검증은 Request DTO와 도메인 경계에서 수행합니다.
• 성공 응답은 ApiResponseBody.success(...)로 감쌉니다.
• 도메인 오류는 {Domain}ErrorCode와 BusinessException을 사용합니다.
• 인증이 필요한 API는 Swagger Security Requirement를 명시합니다.
• Swagger 예시는 공통 응답 Wrapper를 포함해 실제 응답과 맞춥니다.

이미지 업로드

이미지는 백엔드로 직접 전송하지 않고 Presigned URL을 발급받아 S3에 업로드합니다.

1. POST /api/v1/files/presigned-url 요청
2. 응답의 uploadUrl에 동일한 Content-Type으로 PUT
3. 도메인 API에는 fileUrl 또는 fileKey 전달

상세 내용은 Presigned URL Upload를 확인합니다.