1. 인증 API (Auth API)

1.1. 1️⃣ 회원가입 (POST /api/v1/auth/signup)

새로운 사용자를 회원으로 등록합니다. 요청 시 이름, 이메일, 비밀번호를 입력해야 하며, 중복된 이메일은 사용할 수 없습니다.

1.1.1. 요청 예시

POST /api/v1/auth/signup HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 91
Host: localhost:8080

{
  "username" : "hello",
  "email" : "hello@naver.com",
  "password" : "hello123!@#"
}

1.1.2. 응답 예시

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 372

{
  "httpStatus" : "CREATED",
  "code" : 201,
  "success" : true,
  "message" : "회원가입이 완료되었습니다.",
  "data" : {
    "userId" : 1,
    "username" : "hello",
    "email" : "hello@naver.com",
    "role" : "ROLE_USER",
    "point" : 1000,
    "createdAt" : "2025-11-19T10:10:02.7811686"
  },
  "timestamp" : "2025-11-19T10:10:02.8011933"
}

1.1.3. 요청 필드 설명

Path Type Description

username

String

사용자 이름

email

String

사용자 이메일

password

String

비밀번호

1.1.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.userId

Number

회원 ID

data.username

String

회원 이름

data.email

String

회원 이메일

data.role

String

회원 권한

data.point

Number

초기 포인트

data.createdAt

String

회원가입 일시

1.2. 2️⃣ 회원가입 실패 (이메일 중복 시)

이미 등록된 이메일로 회원가입을 시도할 경우 실패합니다.

1.2.1. 요청 예시

POST /api/v1/auth/signup HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 91
Host: localhost:8080

{
  "username" : "hello",
  "email" : "hello@naver.com",
  "password" : "hello123!@#"
}

1.2.2. 응답 예시

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 238

{
  "httpStatus" : "CONFLICT",
  "code" : 409,
  "success" : false,
  "message" : "이미 존재하는 이메일 입니다.",
  "data" : null,
  "timestamp" : "2025-11-19T10:10:02.8682954",
  "requestUrl" : "/api/v1/auth/signup"
}

1.2.3. 요청 필드 설명

Path Type Description

username

String

사용자 이름

email

String

사용자 이메일

password

String

비밀번호

1.2.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

오류 메시지

data

Null

에러 응답의 경우 항상 null

timestamp

String

응답 시간

requestUrl

String

요청 URL

1.3. 3️⃣ 로그인 (POST /api/v1/auth/login)

등록된 이메일과 비밀번호로 로그인합니다. 로그인이 성공하면 AccessToken과 RefreshToken이 발급됩니다.

1.3.1. 요청 예시

POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 66
Host: localhost:8080

{
  "email" : "hello@naver.com",
  "password" : "hello123!@#"
}

1.3.2. 응답 예시

HTTP/1.1 200 OK
Set-Cookie: refreshToken=refreshToken; Path=/; Max-Age=604800; Expires=Wed, 26 Nov 2025 01:10:02 GMT; Secure; HttpOnly; SameSite=Strict
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 251

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "로그인 되었습니다.",
  "data" : {
    "accessToken" : "accessToken",
    "refreshToken" : "refreshToken"
  },
  "timestamp" : "2025-11-19T10:10:02.8357099"
}

1.3.3. 요청 필드 설명

Path Type Description

email

String

사용자 이메일

password

String

비밀번호

1.3.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.accessToken

String

액세스 토큰

data.refreshToken

String

리프레시 토큰

1.4. 4️⃣ 로그아웃 (POST /api/v1/auth/logout)

현재 로그인된 사용자의 세션(토큰)을 무효화하여 로그아웃합니다. Authorization 헤더 또는 인증된 사용자 정보가 필요합니다.

1.4.1. 요청 예시

POST /api/v1/auth/logout HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

1.4.2. 응답 예시

HTTP/1.1 200 OK
Set-Cookie: refreshToken=; Path=/; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT; Secure; HttpOnly; SameSite=Strict
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 179

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "로그아웃 되었습니다.",
  "data" : null,
  "timestamp" : "2025-11-19T10:10:02.7331296"
}

1.4.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Null

응답 데이터 (null일 수 있음)

1.5. 5️⃣ 회원 탈퇴 (DELETE /api/v1/auth/withdraw)

현재 로그인된 사용자를 탈퇴 처리합니다. 비밀번호를 재입력해야 하며, 탈퇴 시 모든 사용자 데이터가 삭제됩니다.

1.5.1. 요청 예시

DELETE /api/v1/auth/withdraw HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 34
Host: localhost:8080

{
  "password" : "hello123!@#"
}

1.5.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 179

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "회원탈퇴 되었습니다.",
  "data" : null,
  "timestamp" : "2025-11-19T10:10:02.7611467"
}

1.5.3. 요청 필드 설명

Path Type Description

password

String

비밀번호 확인

1.5.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Null

응답 데이터 (null일 수 있음)

1.6. 6️⃣ 토큰 재발급 (POST /api/v1/auth/refresh)

만료된 AccessToken을 갱신하기 위해 RefreshToken을 사용합니다. RefreshToken은 쿠키에 포함되어야 합니다.

1.6.1. 요청 예시

POST /api/v1/auth/refresh HTTP/1.1
Host: localhost:8080
Cookie: refreshToken=validRefreshToken
Content-Type: application/x-www-form-urlencoded

1.6.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 225

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "토큰이 재발급되었습니다.",
  "data" : {
    "accessToken" : "newAccessToken"
  },
  "timestamp" : "2025-11-19T10:10:02.8893554"
}

1.6.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.accessToken

String

새로 발급된 액세스 토큰

2. 베팅 API (Bet API)

2.1. 1️⃣ 베팅 생성 (POST /api/v1/bets)

2.1.1. 요청 예시

POST /api/v1/bets HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 74
Host: localhost:8080

{
  "matchId" : 1,
  "selectedTeam" : "Team_A",
  "betAmount" : 1000
}

2.1.2. 응답 예시

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 369

{
  "httpStatus" : "CREATED",
  "code" : 201,
  "success" : true,
  "message" : "베팅이 완료되었습니다.",
  "data" : {
    "betId" : 1,
    "userId" : 1,
    "selectedTeam" : "Team_A",
    "selectedTeamName" : "T1",
    "betAmount" : 1000,
    "oddsAtBetting" : 1.5,
    "userPointAfter" : 0
  },
  "timestamp" : "2025-11-19T10:10:03.7520565"
}

2.1.3. 요청 필드 설명

Path Type Description

matchId

Number

경기 ID

selectedTeam

String

선택한 팀

betAmount

Number

베팅 금액

2.1.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.betId

Number

베팅 ID

data.userId

Number

사용자 ID

data.selectedTeam

String

선택한 팀

data.selectedTeamName

String

선택한 팀 이름

data.betAmount

Number

베팅 금액

data.oddsAtBetting

Number

베팅 시점 배당률

data.userPointAfter

Number

사용자 포인트 잔액

2.2. 2️⃣ 베팅 취소 (DELETE /api/v1/bets/{betId})

2.2.1. 요청 예시

DELETE /api/v1/bets/1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: localhost:8080

2.2.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 256

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "베팅이 취소되었습니다.",
  "data" : {
    "betId" : 1,
    "refundAmount" : 1000,
    "userPointAfter" : 0
  },
  "timestamp" : "2025-11-19T10:10:03.7217441"
}

2.2.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.betId

Number

베팅 ID

data.refundAmount

Number

환불 금액

data.userPointAfter

Number

사용자 포인트 잔액

2.3. 3️⃣ 베팅 내역 조회 (GET /api/v1/bets/me)

2.3.1. 요청 예시

GET /api/v1/bets/me?page=0&size=10 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: localhost:8080

2.3.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 660

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "베팅 내역이 조회되었습니다.",
  "data" : {
    "content" : [ {
      "betId" : 1,
      "matchBetResponse" : {
        "matchId" : 1,
        "teamA" : "T1",
        "teamB" : "GEN.G",
        "startTime" : "2025-11-20T10:10:03.671681"
      },
      "selectedTeam" : "Team_A",
      "betAmount" : 1000,
      "oddsAtBetting" : 1.5,
      "isWin" : false,
      "createdAt" : "2025-11-19T10:10:03.671681"
    } ],
    "totalElements" : 1,
    "totalPages" : 1,
    "size" : 10,
    "number" : 0
  },
  "timestamp" : "2025-11-19T10:10:03.678328"
}

2.3.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.content[].betId

Number

베팅 ID

data.content[].matchBetResponse.matchId

Number

경기 ID

data.content[].matchBetResponse.teamA

String

팀 A

data.content[].matchBetResponse.teamB

String

팀 B

data.content[].matchBetResponse.startTime

String

경기 시작 시간

data.content[].selectedTeam

String

선택한 팀

data.content[].betAmount

Number

베팅 금액

data.content[].oddsAtBetting

Number

베팅 시점 배당률

data.content[].isWin

Boolean

베팅 성공 여부

data.content[].createdAt

String

베팅 생성 시간

data.totalElements

Number

전체 데이터 개수

data.totalPages

Number

총 페이지 수

data.size

Number

페이지 당 데이터 개수

data.number

Number

현재 페이지 번호

3. 인기 검색어 API (Hotkeyword API)

3.1. 1️⃣ 인기 검색어 top5 조회 (GET /api/v1/hotkeyword)

3.1.1. 요청 예시

GET /api/v1/hotkeyword HTTP/1.1
Host: localhost:8080

3.1.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 277

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "인기 검색어 top5를 조회했습니다.",
  "data" : {
    "hotKeywords" : [ "india", "japan", "england", "america", "korea", "china" ]
  },
  "timestamp" : "2025-11-19T10:10:12.312773"
}

3.1.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.hotKeywords

Array

인기검색어 top5

4. 승률 API (AI API)

4.1. 1️⃣ AI 승률 조회 (POST /api/v1/ai/winningrate)

4.1.1. 요청 예시

Unresolved directive in index.adoc - include::C:\sparta\Project\oddventure\build\generated-snippets/winning-rate-ai-controller-test/provide-winning-rate_success/http-request.adoc[]

4.1.2. 응답 예시

Unresolved directive in index.adoc - include::C:\sparta\Project\oddventure\build\generated-snippets/winning-rate-ai-controller-test/provide-winning-rate_success/http-response.adoc[]

4.1.3. 응답 필드 설명

Unresolved directive in index.adoc - include::C:\sparta\Project\oddventure\build\generated-snippets/winning-rate-ai-controller-test/provide-winning-rate_success/response-fields.adoc[]

5. 사용자 API (User API)

5.1. 1️⃣ 내 프로필 조회 (GET /api/v1/users/me)

현재 로그인된 사용자의 프로필 정보를 조회합니다.

5.1.1. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 369

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "프로필 조회에 성공했습니다.",
  "data" : {
    "userId" : 1,
    "username" : "testuser",
    "email" : "test@test.com",
    "point" : 1000,
    "role" : "ROLE_USER",
    "createdAt" : "2025-11-19T10:10:20.4017483"
  },
  "timestamp" : "2025-11-19T10:10:20.4033099"
}

5.1.2. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.userId

Number

사용자 ID

data.username

String

사용자 이름

data.email

String

사용자 이메일

data.point

Number

보유 포인트

data.role

String

사용자 역할

data.createdAt

String

가입 일시

5.2. 2️⃣ 내 프로필 수정 (PATCH /api/v1/users/me)

현재 로그인된 사용자의 프로필(사용자 이름, 이메일)을 수정합니다.

5.2.1. 요청 예시

PATCH /api/v1/users/me?_csrf=AeaGOC7V3Pjq7fz-J1rwz7cmlIiJzasN_h8bSxhFix_MhPcGZ9XgDUjg7snH3s3OQ3fE-tERuent-sggzikuLnl9ui7-5sRn HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 60
Host: localhost:8080

{
  "username" : "newName",
  "email" : "new@email.com"
}

5.2.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 368

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "프로필 수정에 성공했습니다.",
  "data" : {
    "userId" : 1,
    "username" : "newName",
    "email" : "new@email.com",
    "point" : 1000,
    "role" : "ROLE_USER",
    "createdAt" : "2025-11-19T10:10:20.4442797"
  },
  "timestamp" : "2025-11-19T10:10:20.4498583"
}

5.2.3. 요청 필드 설명

Path Type Description

username

String

변경할 사용자 이름 (2~10자, 선택적)

email

String

변경할 이메일 (형식 준수, 선택적)

5.2.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.userId

Number

사용자 ID

data.username

String

수정된 사용자 이름

data.email

String

수정된 이메일

data.point

Number

보유 포인트

data.role

String

사용자 역할

data.createdAt

String

가입 일시

5.3. 3️⃣ 비밀번호 변경 (PATCH /api/v1/users/password)

현재 로그인된 사용자의 비밀번호를 변경합니다.

5.3.1. 요청 예시

PATCH /api/v1/users/password?_csrf=gOp1NDIvJFa66H-bc9fjmgyN8OZuk8qrHrwSgLMYiuy9uPiQ4t8QUgRJQmGX30yiFfrXqTS-3Ydepa-GeIsjsocu69mLj8Gh HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 87
Host: localhost:8080

{
  "currentPassword" : "currentPassword123!",
  "newPassword" : "newPassword123!"
}

5.3.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 192

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "비밀번호 변경에 성공했습니다.",
  "data" : null,
  "timestamp" : "2025-11-19T10:10:20.4300918"
}

5.3.3. 요청 필드 설명

Path Type Description

currentPassword

String

현재 비밀번호

newPassword

String

새 비밀번호 (영문, 숫자, 특수문자 포함 8~20자)

5.3.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Null

응답 데이터 (null일 수 있음)

6. 경기 API (Match API)

6.1. 1️⃣ 경기 목록 조회 (GET /api/v1/matches)

등록된 경기의 전체 목록을 페이지 형태로 조회합니다. 요청 시 페이지 번호(page)와 크기(size)를 전달할 수 있습니다. 경기는 기본적으로 startTime 기준 오름차순으로 정렬됩니다.

6.1.1. 요청 예시

GET /api/v1/matches?page=0&size=10 HTTP/1.1
Host: localhost:8080

6.1.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 704

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "매치 목록 조회에 성공했습니다.",
  "data" : {
    "content" : [ {
      "matchId" : 1,
      "matchName" : "LCK",
      "teamA" : "T1",
      "teamB" : "GEN.G",
      "totalAmountA" : 10000,
      "totalAmountB" : 8000,
      "startTime" : "2025-10-16T18:00:00",
      "endTime" : "2025-10-16T20:00:00",
      "status" : "SCHEDULED",
      "winner" : null,
      "loser" : null,
      "viewCount" : 153,
      "createdAt" : "2025-10-10T20:00:00"
    } ],
    "totalElements" : 1,
    "totalPages" : 1,
    "size" : 10,
    "number" : 0
  },
  "timestamp" : "2025-11-19T10:10:16.4198918"
}

6.1.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.content[].matchId

Number

매치 ID

data.content[].matchName

String

매치명

data.content[].teamA

String

팀 A

data.content[].teamB

String

팀 B

data.content[].totalAmountA

Number

팀 A 베팅 총액

data.content[].totalAmountB

Number

팀 B 베팅 총액

data.content[].startTime

String

매치 시작 시간

data.content[].endTime

String

매치 종료 시간

data.content[].status

String

매치 상태

data.content[].winner

String

승리 팀

data.content[].loser

String

패배 팀

data.content[].viewCount

Number

조회수

data.content[].createdAt

String

생성일시

data.totalElements

Number

전체 데이터 개수

data.totalPages

Number

총 페이지 수

data.size

Number

페이지당 데이터 개수

data.number

Number

현재 페이지 번호

6.2. 2️⃣ 경기 상세 조회 (GET /api/v1/matches/{matchId})

특정 경기의 상세 정보를 조회합니다. 경기 ID(matchId)를 경로 변수로 전달해야 합니다.

6.2.1. 요청 예시

GET /api/v1/matches/1 HTTP/1.1
Host: localhost:8080

6.2.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 562

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "매치 상세 조회에 성공했습니다.",
  "data" : {
    "matchId" : 1,
    "matchName" : "LCK",
    "teamA" : "T1",
    "teamB" : "GEN.G",
    "totalAmountA" : 10000,
    "totalAmountB" : 8000,
    "startTime" : "2025-10-16T18:00:00",
    "endTime" : "2025-10-16T20:00:00",
    "status" : "SCHEDULED",
    "winner" : null,
    "loser" : null,
    "viewCount" : 153,
    "createdAt" : "2025-10-10T20:00:00"
  },
  "timestamp" : "2025-11-19T10:10:16.3656292"
}

6.2.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.matchId

Number

매치 ID

data.matchName

String

매치명

data.teamA

String

팀 A

data.teamB

String

팀 B

data.totalAmountA

Number

팀 A 베팅 총액

data.totalAmountB

Number

팀 B 베팅 총액

data.startTime

String

매치 시작 시간

data.endTime

String

매치 종료 시간

data.status

String

매치 상태

data.winner

String

승리 팀

data.loser

String

패배 팀

data.viewCount

Number

조회수

data.createdAt

String

생성일시

6.3. 3️⃣ 경기 검색 (POST /api/v1/matches/search)

경기 이름, 상태, 날짜 등 검색 조건을 바탕으로 경기를 조회합니다. 검색 조건은 JSON Body로 전달하며, 페이징 처리와 함께 결과를 반환합니다.

6.3.1. 요청 예시

POST /api/v1/matches/search?page=0&size=10 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 64
Host: localhost:8080

{
  "keyword" : "",
  "fromDate" : null,
  "toDate" : null
}

6.3.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 721

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "검색 조건에 맞는 매치 목록을 조회했습니다.",
  "data" : {
    "content" : [ {
      "matchId" : 1,
      "matchName" : "LCK",
      "teamA" : "T1",
      "teamB" : "GEN.G",
      "totalAmountA" : 10000,
      "totalAmountB" : 8000,
      "startTime" : "2025-10-16T18:00:00",
      "endTime" : "2025-10-16T20:00:00",
      "status" : "SCHEDULED",
      "winner" : null,
      "loser" : null,
      "viewCount" : 153,
      "createdAt" : "2025-10-10T20:00:00"
    } ],
    "totalElements" : 1,
    "totalPages" : 1,
    "size" : 10,
    "number" : 0
  },
  "timestamp" : "2025-11-19T10:10:16.3936661"
}

6.3.3. 요청 필드 설명

Path Type Description

keyword

String

검색 키워드 (팀명, 매치명 등)

fromDate

String

검색 시작일시 (예: 2025-11-01T00:00:00)

toDate

String

검색 종료일시 (예: 2025-11-12T23:59:59)

6.3.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.content[].matchId

Number

매치 ID

data.content[].matchName

String

매치명

data.content[].teamA

String

팀 A

data.content[].teamB

String

팀 B

data.content[].totalAmountA

Number

팀 A 베팅 총액

data.content[].totalAmountB

Number

팀 B 베팅 총액

data.content[].startTime

String

매치 시작 시간

data.content[].endTime

String

매치 종료 시간

data.content[].status

String

매치 상태

data.content[].winner

String

승리 팀

data.content[].loser

String

패배 팀

data.content[].viewCount

Number

조회수

data.content[].createdAt

String

생성일시

data.totalElements

Number

전체 데이터 개수

data.totalPages

Number

총 페이지 수

data.size

Number

페이지당 데이터 개수

data.number

Number

현재 페이지 번호

7. 관리자 API (Admin API)

7.1. 1️⃣ 매치 생성 (POST /api/v1/admin/matches)

새로운 경기를 생성합니다.

7.1.1. 요청 예시

POST /api/v1/admin/matches HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: localhost:8080

7.1.2. 응답 예시

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 238

{
  "httpStatus" : "CREATED",
  "code" : 201,
  "success" : true,
  "message" : "매치가 생성되었습니다.",
  "data" : {
    "totalMatches" : 1,
    "fetchIds" : [ 1 ]
  },
  "timestamp" : "2025-11-19T10:09:58.7873267"
}

7.1.3. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.totalMatches

Number

생성된 매치 개수

data.fetchIds

Array

생성된 패치 ID 목록

7.2. 2️⃣ 매치 정보 수정 (PATCH /api/v1/admin/matches/{matchId})

기존 경기의 정보를 수정합니다.

7.2.1. 요청 예시

PATCH /api/v1/admin/matches/1?_csrf=PGddjj6jppuOCCK0NXEQhq6kkk95xnMBwzhIcL3BnrrkyjylCAU56g6VlfqjMUfWBVwktc-Svy5IpUEspw4rQYrxqoPX_V-c HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 146
Host: localhost:8080

{
  "matchName" : "LCK",
  "teamA" : "New Team A",
  "teamB" : "New Team B",
  "startTime" : "2025-11-21T10:09:59",
  "status" : "ONGOING"
}

7.2.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 363

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "매치 정보가 수정되었습니다.",
  "data" : {
    "matchId" : 1,
    "matchName" : "LCK",
    "teamA" : "New Team A",
    "teamB" : "New Team B",
    "startTime" : "2025-11-21T10:09:59",
    "status" : "ONGOING"
  },
  "timestamp" : "2025-11-19T10:09:59.2967345"
}

7.2.3. 경로 파라미터 설명

Table 1. /api/v1/admin/matches/{matchId}
Parameter Description

matchId

수정할 경기 ID

7.2.4. 요청 필드 설명

Path Type Description

matchName

String

변경할 경기 이름 (선택적)

teamA

String

변경할 A팀 이름 (선택적)

teamB

String

변경할 B팀 이름 (선택적)

startTime

String

변경할 경기 시작 시간 (선택적)

status

String

변경할 경기 상태 (선택적)

7.2.5. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.matchId

Number

수정된 경기 ID

data.matchName

String

수정된 경기 이름

data.teamA

String

수정된 A팀 이름

data.teamB

String

수정된 B팀 이름

data.startTime

String

수정된 경기 시작 시간

data.status

String

수정된 경기 상태 (SCHEDULED, ONGOING, FINISHED)

7.3. 3️⃣ 전체 사용자 목록 조회 (GET /api/v1/admin/users)

조건에 맞는 사용자 목록을 페이징하여 조회합니다.

7.3.1. 요청 예시

GET /api/v1/admin/users?email=test&username=user&page=0&size=5 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: localhost:8080

7.3.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 506

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "사용자 목록 조회에 성공했습니다.",
  "data" : {
    "content" : [ {
      "userId" : 1,
      "username" : "testuser1",
      "email" : "test1@email.com",
      "point" : 1000,
      "role" : "ROLE_USER",
      "createdAt" : "2025-11-19T10:10:00.0003251"
    } ],
    "totalElements" : 1,
    "totalPages" : 1,
    "size" : 5,
    "number" : 0
  },
  "timestamp" : "2025-11-19T10:10:00.0239609"
}

7.3.3. 쿼리 파라미터 설명

Parameter Description

email

검색할 이메일 (선택적)

username

검색할 사용자 이름 (선택적)

page

페이지 번호 (0부터 시작)

size

페이지 당 항목 수

7.3.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.content[]

Array

사용자 정보 목록

data.content[].userId

Number

사용자 ID

data.content[].username

String

사용자 이름

data.content[].email

String

사용자 이메일

data.content[].point

Number

보유 포인트

data.content[].role

String

사용자 역할

data.content[].createdAt

String

가입 일시

data.totalElements

Number

전체 항목 수

data.totalPages

Number

전체 페이지 수

data.size

Number

페이지 크기

data.number

Number

현재 페이지 번호 (0부터 시작)

7.4. 4️⃣ 사용자 상세 조회 (GET /api/v1/admin/users/{userId})

특정 사용자의 상세 정보를 조회합니다.

7.4.1. 요청 예시

GET /api/v1/admin/users/1 HTTP/1.1
Host: localhost:8080

7.4.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 383

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "사용자 상세 정보 조회에 성공했습니다.",
  "data" : {
    "userId" : 1,
    "username" : "testuser",
    "email" : "test@test.com",
    "point" : 1000,
    "role" : "ROLE_USER",
    "createdAt" : "2025-11-19T10:10:00.1973898"
  },
  "timestamp" : "2025-11-19T10:10:00.1988939"
}

7.4.3. 경로 파라미터 설명

Table 2. /api/v1/admin/users/{userId}
Parameter Description

userId

조회할 사용자 ID

7.4.4. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.userId

Number

사용자 ID

data.username

String

사용자 이름

data.email

String

사용자 이메일

data.point

Number

보유 포인트

data.role

String

사용자 역할

data.createdAt

String

가입 일시

7.5. 5️⃣ 사용자 포인트 지급 (POST /api/v1/admin/users/{userId}/points)

특정 사용자의 포인트를 수동으로 조정합니다.

7.5.1. 요청 예시

POST /api/v1/admin/users/1/points?_csrf=_KBCv9OK9mzcEefv5vDgNtNl3iCvhqNMYi7_LSw_IJczLdGkyZcj2eq9xFXxc9DW1t3UVeJV80HOvpBhBxbLGk8MRKNVT7eR HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 61
Host: localhost:8080

{
  "amount" : 5000,
  "reason" : "베팅 승리 보상"
}

7.5.2. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 297

{
  "httpStatus" : "OK",
  "code" : 200,
  "success" : true,
  "message" : "포인트 지급에 성공했습니다.",
  "data" : {
    "userId" : 1,
    "username" : "testuser",
    "adjustedAmount" : 5000,
    "finalBalance" : 6000
  },
  "timestamp" : "2025-11-19T10:10:00.1041411"
}

7.5.3. 경로 파라미터 설명

Table 3. /api/v1/admin/users/{userId}/points
Parameter Description

userId

포인트를 조정할 사용자 ID

7.5.4. 요청 필드 설명

Path Type Description

amount

Number

조정할 포인트 (양수: 지급)

reason

String

조정 사유 (로그 기록용)

7.5.5. 응답 필드 설명

Path Type Description

httpStatus

String

HTTP 상태 코드

code

Number

응답 코드

success

Boolean

성공 여부

message

String

응답 메시지

timestamp

String

응답 시간

data

Object

응답 데이터

data.userId

Number

사용자 ID

data.username

String

사용자 이름

data.adjustedAmount

Number

조정된 포인트

data.finalBalance

Number

조정 후 최종 포인트