1. 공통 응답 형식

이 API는 엔드포인트 성격에 따라 아래 응답 형식을 사용합니다.

1.1. 목록 조회 응답 (페이지네이션)

목록 조회 API는 items, page, pageSize, `total`을 포함한 페이지네이션 구조를 사용합니다.

{
  "items": [
    {
      "...": "리소스 필드"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 120
}

1.2. 단건 조회 응답

단건 조회 API는 해당 리소스 객체를 그대로 반환합니다.

{
  "id": "uuid",
  "...": "리소스 필드"
}

1.3. 파일 다운로드 응답

파일 조회 API(/media/{id})는 JSON이 아닌 바이너리 본문을 반환하며, `Content-Type`은 파일 형식에 따라 달라집니다.

2. 인증(Auth)

2.1. 카카오 로그인

2.1.1. 요청 예시

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

{
  "code" : "kakao-auth-code"
}

2.1.2. 요청 필드

Path Type Description

code

String

카카오 인가 코드

redirectUri

String

인가 요청에 사용한 redirect URI

2.1.3. 응답 필드

경로 타입 설명

accessToken

String

서비스 Access Token

refreshToken

String

서비스 Refresh Token

tokenType

String

토큰 타입(Bearer)

accessTokenExpiresIn

Number

Access Token 만료(초)

refreshTokenExpiresIn

Number

Refresh Token 만료(초)

registrationRequired

Boolean

회원가입 정보 입력 필요 여부

2.1.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 201

{
  "accessToken" : "access-token",
  "refreshToken" : "refresh-token",
  "tokenType" : "Bearer",
  "accessTokenExpiresIn" : 3600,
  "refreshTokenExpiresIn" : 1209600,
  "registrationRequired" : true
}

2.1.5. 응답 본문(JSON)

{
  "accessToken" : "access-token",
  "refreshToken" : "refresh-token",
  "tokenType" : "Bearer",
  "accessTokenExpiresIn" : 3600,
  "refreshTokenExpiresIn" : 1209600,
  "registrationRequired" : true
}

2.2. 토큰 재발급

2.2.1. 요청 예시

POST /auth/refresh HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 38
Host: localhost:8080

{
  "refreshToken" : "refresh-token"
}

2.2.2. 요청 필드

Path Type Description

refreshToken

String

기존 Refresh Token

2.2.3. 응답 필드

경로 타입 설명

accessToken

String

재발급된 Access Token

refreshToken

String

재발급된 Refresh Token

tokenType

String

토큰 타입(Bearer)

accessTokenExpiresIn

Number

Access Token 만료(초)

refreshTokenExpiresIn

Number

Refresh Token 만료(초)

registrationRequired

Boolean

회원가입 정보 입력 필요 여부

2.2.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 210

{
  "accessToken" : "new-access-token",
  "refreshToken" : "new-refresh-token",
  "tokenType" : "Bearer",
  "accessTokenExpiresIn" : 3600,
  "refreshTokenExpiresIn" : 1209600,
  "registrationRequired" : false
}

2.2.5. 응답 본문(JSON)

{
  "accessToken" : "new-access-token",
  "refreshToken" : "new-refresh-token",
  "tokenType" : "Bearer",
  "accessTokenExpiresIn" : 3600,
  "refreshTokenExpiresIn" : 1209600,
  "registrationRequired" : false
}

2.3. 회원가입 정보 등록

2.3.1. 요청 예시

POST /auth/register HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 195
Host: localhost:8080

{
  "userType" : "STUDENT",
  "name" : "홍길동",
  "email" : "hong@example.com",
  "department" : "소프트웨어학과",
  "phoneNumber" : "010-1234-5678",
  "studentNumber" : "2020123456"
}

2.3.2. 요청 필드

Path Type Description

userType

String

회원 유형(VISITOR, STUDENT, STAFF, PROFESSOR)

name

String

이름

email

String

이메일

department

String

소속

phoneNumber

String

연락처

studentNumber

String

학번

2.3.3. 응답 예시

HTTP/1.1 204 No Content
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

3. 전시(Exhibition)

3.1. 전시 목록 조회

3.1.1. 요청 예시

GET /exhibitions?q=cse&slug=sw-gp HTTP/1.1
Host: localhost:8080

3.1.2. 쿼리 파라미터

이름 설명

q

전시회명 검색어

slug

전시회 slug (정확히 일치)

3.1.3. 응답 필드

경로 타입 설명

items

Array

전시회 목록

items[].id

String

전시회 ID

items[].slug

String

전시회 slug

items[].defaultDomain

String

기본 전시 도메인

items[].customDomain

String

커스텀 전시 도메인

items[].name

String

전시회명

items[].description

String

전시회 설명

items[].logoMediaId

Null

로고 미디어 ID

items[].bannerEnabled

Boolean

배너 사용 여부

items[].bannerMediaId

Null

배너 미디어 ID

items[].popupEnabled

Boolean

팝업 사용 여부

items[].popupImageMediaId

Null

팝업 이미지 미디어 ID

items[].popupUrl

Null

팝업 링크 URL

items[].introTitle

Null

인트로 제목

items[].introDescription

Null

인트로 설명

items[].introVideoMediaId

Null

인트로 비디오 미디어 ID

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

3.1.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 595

{
  "items" : [ {
    "id" : "00097f71-bd5f-4d62-ae48-f2cb931bb3d5",
    "slug" : "sw-gp",
    "defaultDomain" : "exhibition.scg.skku.ac.kr",
    "customDomain" : "custom.exhibition.scg.sh",
    "name" : "소프트웨어융합대학 졸업작품 전시회",
    "description" : "설명",
    "logoMediaId" : null,
    "bannerEnabled" : false,
    "bannerMediaId" : null,
    "popupEnabled" : false,
    "popupImageMediaId" : null,
    "popupUrl" : null,
    "introTitle" : null,
    "introDescription" : null,
    "introVideoMediaId" : null
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

3.1.5. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "00097f71-bd5f-4d62-ae48-f2cb931bb3d5",
    "slug" : "sw-gp",
    "defaultDomain" : "exhibition.scg.skku.ac.kr",
    "customDomain" : "custom.exhibition.scg.sh",
    "name" : "소프트웨어융합대학 졸업작품 전시회",
    "description" : "설명",
    "logoMediaId" : null,
    "bannerEnabled" : false,
    "bannerMediaId" : null,
    "popupEnabled" : false,
    "popupImageMediaId" : null,
    "popupUrl" : null,
    "introTitle" : null,
    "introDescription" : null,
    "introVideoMediaId" : null
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

3.2. 단일 전시 조회

3.2.1. 경로 파라미터

이름 설명

id

전시회 ID 형식의 더미 값 (실제 조회는 현재 요청 도메인 기준)

3.2.2. 요청 예시

GET /exhibitions/2c126496-7533-4401-b8e5-ca14178348d5 HTTP/1.1
Host: localhost:8080

3.2.3. 응답 필드

경로 타입 설명

id

String

전시회 ID

slug

String

전시회 slug

defaultDomain

String

기본 전시 도메인

customDomain

String

커스텀 전시 도메인

name

String

전시회명

description

String

전시회 설명

logoMediaId

Null

로고 미디어 ID

bannerEnabled

Boolean

배너 사용 여부

bannerMediaId

Null

배너 미디어 ID

popupEnabled

Boolean

팝업 사용 여부

popupImageMediaId

Null

팝업 이미지 미디어 ID

popupUrl

Null

팝업 링크 URL

introTitle

Null

인트로 제목

introDescription

Null

인트로 설명

introVideoMediaId

Null

인트로 비디오 미디어 ID

3.2.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 496

{
  "id" : "2c126496-7533-4401-b8e5-ca14178348d5",
  "slug" : "sw-gp",
  "defaultDomain" : "exhibition.scg.skku.ac.kr",
  "customDomain" : "custom.exhibition.scg.sh",
  "name" : "소프트웨어융합대학 졸업작품 전시회",
  "description" : "설명",
  "logoMediaId" : null,
  "bannerEnabled" : false,
  "bannerMediaId" : null,
  "popupEnabled" : false,
  "popupImageMediaId" : null,
  "popupUrl" : null,
  "introTitle" : null,
  "introDescription" : null,
  "introVideoMediaId" : null
}

3.2.5. 응답 본문(JSON)

{
  "id" : "2c126496-7533-4401-b8e5-ca14178348d5",
  "slug" : "sw-gp",
  "defaultDomain" : "exhibition.scg.skku.ac.kr",
  "customDomain" : "custom.exhibition.scg.sh",
  "name" : "소프트웨어융합대학 졸업작품 전시회",
  "description" : "설명",
  "logoMediaId" : null,
  "bannerEnabled" : false,
  "bannerMediaId" : null,
  "popupEnabled" : false,
  "popupImageMediaId" : null,
  "popupUrl" : null,
  "introTitle" : null,
  "introDescription" : null,
  "introVideoMediaId" : null
}

3.3. 도메인으로 slug 조회

3.3.1. 요청 예시

GET /exhibitions/slug HTTP/1.1
Host: localhost:8080

3.3.2. 응답 필드

경로 타입 설명

slug

String

현재 도메인에 매핑된 전시회 slug

3.3.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 22

{
  "slug" : "sw-gp"
}

3.3.4. 응답 본문(JSON)

{
  "slug" : "sw-gp"
}

4. 카테고리(Category)

4.1. 카테고리 목록 조회

4.1.1. 요청 예시

GET /categories HTTP/1.1
Host: localhost:8080

4.1.2. 응답 필드

경로 타입 설명

items

Array

카테고리 목록

items[].id

String

카테고리 ID

items[].exhibitionId

String

전시 ID

items[].slug

String

카테고리 슬러그

items[].name

String

카테고리명

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

4.1.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 221

{
  "items" : [ {
    "id" : "43c9c45b-2053-4593-8980-651078695d5a",
    "exhibitionId" : "b93b5717-5830-448b-a52f-c37cfa86f402",
    "slug" : "ai",
    "name" : "AI"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

4.1.4. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "43c9c45b-2053-4593-8980-651078695d5a",
    "exhibitionId" : "b93b5717-5830-448b-a52f-c37cfa86f402",
    "slug" : "ai",
    "name" : "AI"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

4.2. 단일 카테고리 조회

4.2.1. 요청 예시

GET /categories/0eb1c324-8f7b-4a20-a90d-9f00064918c4 HTTP/1.1
Host: localhost:8080

4.2.2. 응답 필드

경로 타입 설명

id

String

카테고리 ID

exhibitionId

String

전시 ID

slug

String

카테고리 슬러그

name

String

카테고리명

4.2.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 146

{
  "id" : "0eb1c324-8f7b-4a20-a90d-9f00064918c4",
  "exhibitionId" : "9e154772-35ed-48f1-afb1-602ef592a99b",
  "slug" : "web",
  "name" : "Web"
}

4.2.4. 응답 본문(JSON)

{
  "id" : "0eb1c324-8f7b-4a20-a90d-9f00064918c4",
  "exhibitionId" : "9e154772-35ed-48f1-afb1-602ef592a99b",
  "slug" : "web",
  "name" : "Web"
}

5. 항목(Item)

5.1. 항목 목록 조회

5.1.1. 쿼리 파라미터

이름 설명

categoryId

카테고리 ID

categorySlug

카테고리 슬러그

eventPeriodId

이벤트 기간 ID

classificationId

분야(분류) ID

awarded

수상 여부 필터 (true: 수상작만, false: 미수상작만)

q

검색어 (제목, 지도교수, 학생명)

page

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

size

페이지 크기

sort

정렬 (예: title,asc 또는 createdAt,desc)

5.1.2. 요청 예시

GET /items HTTP/1.1
Host: localhost:8080

5.1.3. 응답 필드

경로 타입 설명

items

Array

아이템 목록

items[].id

String

아이템 ID

items[].exhibitionId

String

전시 ID

items[].categoryId

String

카테고리 ID

items[].eventPeriodId

Null

이벤트 기간 ID

items[].title

String

제목

items[].description

String

설명

items[].participantNames

String

참여자명단: 쉼표로 구분됨

items[].participantEmails

String

발표자 이메일 명단: 쉼표로 구분됨

items[].advisorNames

String

지도교수명단: 쉼표로 구분됨

items[].thumbnailMediaId

Null

썸네일 미디어 ID

items[].posterMediaId

Null

포스터 미디어 ID

items[].presentationVideoMediaId

Null

발표 영상 미디어 ID

items[].awarded

Boolean

수상 여부

items[].likes

Number

좋아요 수

items[].isLike

Boolean

현재 로그인 사용자의 좋아요 여부 (비로그인 시 false)

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

5.1.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 607

{
  "items" : [ {
    "id" : "9c1d5bb1-ff09-4f39-87f7-69b388a74fea",
    "exhibitionId" : "60caacd4-d78c-44e1-96d9-ae2ae8652105",
    "categoryId" : "17b9547a-fea0-4805-9556-7378fbc3dc5b",
    "eventPeriodId" : null,
    "title" : "Smart Campus",
    "description" : "desc",
    "participantNames" : "홍길동",
    "participantEmails" : "hong@example.com",
    "advisorNames" : "김교수",
    "thumbnailMediaId" : null,
    "posterMediaId" : null,
    "presentationVideoMediaId" : null,
    "awarded" : false,
    "likes" : 0,
    "isLike" : false
  } ],
  "page" : 1,
  "pageSize" : 20,
  "total" : 1
}

5.1.5. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "9c1d5bb1-ff09-4f39-87f7-69b388a74fea",
    "exhibitionId" : "60caacd4-d78c-44e1-96d9-ae2ae8652105",
    "categoryId" : "17b9547a-fea0-4805-9556-7378fbc3dc5b",
    "eventPeriodId" : null,
    "title" : "Smart Campus",
    "description" : "desc",
    "participantNames" : "홍길동",
    "participantEmails" : "hong@example.com",
    "advisorNames" : "김교수",
    "thumbnailMediaId" : null,
    "posterMediaId" : null,
    "presentationVideoMediaId" : null,
    "awarded" : false,
    "likes" : 0,
    "isLike" : false
  } ],
  "page" : 1,
  "pageSize" : 20,
  "total" : 1
}

5.2. 단일 항목 조회

5.2.1. 경로 파라미터

이름 설명

id

아이템 ID

5.2.2. 요청 예시

GET /items/6ae24208-0075-4189-ba40-e60371ef89f4 HTTP/1.1
Host: localhost:8080

5.2.3. 응답 필드

경로 타입 설명

id

String

아이템 ID

exhibitionId

String

전시 ID

categoryId

String

카테고리 ID

eventPeriodId

String

이벤트 기간 ID

title

String

제목

description

String

설명

participantNames

String

참여자 명단: 쉼표로 구분됨

participantEmails

String

발표자 이메일 명단: 쉼표로 구분됨

advisorNames

String

지도교수 명단: 쉼표로 구분됨

thumbnailMediaId

Null

썸네일 미디어 ID

posterMediaId

Null

포스터 미디어 ID

presentationVideoMediaId

Null

발표 영상 미디어 ID

awarded

Boolean

수상 여부

likes

Number

좋아요 수

isLike

Boolean

현재 로그인 사용자의 좋아요 여부 (비로그인 시 false)

5.2.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 568

{
  "id" : "6ae24208-0075-4189-ba40-e60371ef89f4",
  "exhibitionId" : "48fddaa9-b051-408b-868f-00412c016fa0",
  "categoryId" : "a9dc1c16-46ef-4c28-a49a-1532196a87e4",
  "eventPeriodId" : "be92771c-4081-4a08-be66-2703f63631fe",
  "title" : "Smart Campus",
  "description" : "desc",
  "participantNames" : "홍길동,양현준",
  "participantEmails" : "hong@example.com,yang@example.com",
  "advisorNames" : "김교수",
  "thumbnailMediaId" : null,
  "posterMediaId" : null,
  "presentationVideoMediaId" : null,
  "awarded" : false,
  "likes" : 0,
  "isLike" : false
}

5.2.5. 응답 본문(JSON)

{
  "id" : "6ae24208-0075-4189-ba40-e60371ef89f4",
  "exhibitionId" : "48fddaa9-b051-408b-868f-00412c016fa0",
  "categoryId" : "a9dc1c16-46ef-4c28-a49a-1532196a87e4",
  "eventPeriodId" : "be92771c-4081-4a08-be66-2703f63631fe",
  "title" : "Smart Campus",
  "description" : "desc",
  "participantNames" : "홍길동,양현준",
  "participantEmails" : "hong@example.com,yang@example.com",
  "advisorNames" : "김교수",
  "thumbnailMediaId" : null,
  "posterMediaId" : null,
  "presentationVideoMediaId" : null,
  "awarded" : false,
  "likes" : 0,
  "isLike" : false
}

5.3. 항목 좋아요 추가

5.3.1. 경로 파라미터

이름 설명

id

아이템 ID

5.3.2. 요청 헤더

Name Description

Authorization

Bearer Access Token

5.3.3. 요청 예시

POST /items/ba626e08-a283-4775-9220-e5ec5368180b/like HTTP/1.1
Authorization: Bearer {accessToken}
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

5.3.4. 응답 예시

HTTP/1.1 201 Created
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

5.4. 항목 좋아요 취소

5.4.1. 경로 파라미터

이름 설명

id

아이템 ID

5.4.2. 요청 헤더

Name Description

Authorization

Bearer Access Token

5.4.3. 요청 예시

DELETE /items/4f36e182-7ed6-4785-933c-6f7bfdbdc01c/like HTTP/1.1
Authorization: Bearer {accessToken}
Host: localhost:8080

5.4.4. 응답 예시

HTTP/1.1 204 No Content
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

6. 분류(Classification)

6.1. 분류 목록 조회

6.1.1. 요청 예시

GET /classifications HTTP/1.1
Host: localhost:8080

6.1.2. 응답 필드

경로 타입 설명

items

Array

분류 목록

items[].id

String

분류 ID

items[].exhibitionId

String

전시 ID

items[].name

String

분류명

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

6.1.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 206

{
  "items" : [ {
    "id" : "b44dc3bf-f2c1-44fa-a20c-bae1ece49ab4",
    "exhibitionId" : "ca5d18b5-d7eb-46ca-81f9-1d894a303afa",
    "name" : "작품"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

6.1.4. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "b44dc3bf-f2c1-44fa-a20c-bae1ece49ab4",
    "exhibitionId" : "ca5d18b5-d7eb-46ca-81f9-1d894a303afa",
    "name" : "작품"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

6.2. 단일 분류 조회

6.2.1. 요청 예시

GET /classifications/bce7f55e-7704-40ab-a176-1f2e374899c3 HTTP/1.1
Host: localhost:8080

6.2.2. 응답 필드

경로 타입 설명

id

String

분류 ID

exhibitionId

String

전시 ID

name

String

분류명: ex. 논문, 작품 등

6.2.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 131

{
  "id" : "bce7f55e-7704-40ab-a176-1f2e374899c3",
  "exhibitionId" : "5c8e75a1-cce2-4bf8-b503-5130abef595d",
  "name" : "논문"
}

6.2.4. 응답 본문(JSON)

{
  "id" : "bce7f55e-7704-40ab-a176-1f2e374899c3",
  "exhibitionId" : "5c8e75a1-cce2-4bf8-b503-5130abef595d",
  "name" : "논문"
}

7. 이벤트 기간(Event Period)

7.1. 이벤트 기간 목록 조회

7.1.1. 요청 예시

GET /event-periods HTTP/1.1
Host: localhost:8080

7.1.2. 응답 필드

경로 타입 설명

items

Array

이벤트 기간 목록

items[].id

String

이벤트 기간 ID

items[].exhibitionId

String

전시 ID

items[].name

String

이벤트 기간명

items[].startTime

String

시작 시각

items[].endTime

String

종료 시각

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

7.1.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 294

{
  "items" : [ {
    "id" : "905bab61-2e58-4e53-9f91-5fe5eef32b2f",
    "exhibitionId" : "ce2b1df0-22e8-4887-a315-3ce8d41e36e2",
    "name" : "2025-1학기",
    "startTime" : "2025-03-01T00:00:00Z",
    "endTime" : "2025-06-30T00:00:00Z"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

7.1.4. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "905bab61-2e58-4e53-9f91-5fe5eef32b2f",
    "exhibitionId" : "ce2b1df0-22e8-4887-a315-3ce8d41e36e2",
    "name" : "2025-1학기",
    "startTime" : "2025-03-01T00:00:00Z",
    "endTime" : "2025-06-30T00:00:00Z"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

7.2. 단일 이벤트 기간 조회

7.2.1. 요청 예시

GET /event-periods/0b636751-7942-4cca-a5b1-0697fcc3df20 HTTP/1.1
Host: localhost:8080

7.2.2. 응답 필드

경로 타입 설명

id

String

이벤트 기간 ID

exhibitionId

String

전시 ID

name

String

이벤트 기간명

startTime

String

시작 시각

endTime

String

종료 시각

7.2.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 215

{
  "id" : "0b636751-7942-4cca-a5b1-0697fcc3df20",
  "exhibitionId" : "e333f66d-b50e-4d19-a953-5381c2707f46",
  "name" : "2025-2학기",
  "startTime" : "2025-09-01T00:00:00Z",
  "endTime" : "2025-12-31T00:00:00Z"
}

7.2.4. 응답 본문(JSON)

{
  "id" : "0b636751-7942-4cca-a5b1-0697fcc3df20",
  "exhibitionId" : "e333f66d-b50e-4d19-a953-5381c2707f46",
  "name" : "2025-2학기",
  "startTime" : "2025-09-01T00:00:00Z",
  "endTime" : "2025-12-31T00:00:00Z"
}

8. 게시판(Board)

8.1. 게시판 목록 조회

8.1.1. 요청 예시

GET /boards HTTP/1.1
Host: localhost:8080

8.1.2. 응답 필드

경로 타입 설명

items

Array

게시판 목록

items[].id

String

게시판 글 ID

items[].exhibitionId

String

전시 ID

items[].title

String

제목

items[].content

String

내용

items[].attachmentMediaIds

Array

첨부 미디어 ID 목록

items[].attachmentMedias

Array

첨부 미디어 목록

items[].attachmentMedias[].id

String

첨부 미디어 ID

items[].attachmentMedias[].fileName

String

첨부 미디어 파일명

items[].authorUserId

String

작성자 사용자 ID

items[].createdAt

String

생성 일시

items[].updatedAt

String

수정 일시

page

Number

페이지 번호

pageSize

Number

페이지 크기

total

Number

전체 건수

8.1.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 598

{
  "items" : [ {
    "id" : "b0beb122-06fe-40ee-96da-f950d62240d9",
    "exhibitionId" : "b723777a-d434-47c4-8923-dbb6d52a33ba",
    "title" : "공지",
    "content" : "안내 내용",
    "attachmentMediaIds" : [ "6d9fa73b-4350-42d2-abff-b35d6e77f3af" ],
    "attachmentMedias" : [ {
      "id" : "6d9fa73b-4350-42d2-abff-b35d6e77f3af",
      "fileName" : "notice-list.pdf"
    } ],
    "authorUserId" : "219017a5-1ffa-4ca3-be4e-16bbc7d6351f",
    "createdAt" : "2026-04-16T00:18:04.809396Z",
    "updatedAt" : "2026-04-16T00:18:04.809397Z"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

8.1.4. 응답 본문(JSON)

{
  "items" : [ {
    "id" : "b0beb122-06fe-40ee-96da-f950d62240d9",
    "exhibitionId" : "b723777a-d434-47c4-8923-dbb6d52a33ba",
    "title" : "공지",
    "content" : "안내 내용",
    "attachmentMediaIds" : [ "6d9fa73b-4350-42d2-abff-b35d6e77f3af" ],
    "attachmentMedias" : [ {
      "id" : "6d9fa73b-4350-42d2-abff-b35d6e77f3af",
      "fileName" : "notice-list.pdf"
    } ],
    "authorUserId" : "219017a5-1ffa-4ca3-be4e-16bbc7d6351f",
    "createdAt" : "2026-04-16T00:18:04.809396Z",
    "updatedAt" : "2026-04-16T00:18:04.809397Z"
  } ],
  "page" : 1,
  "pageSize" : 1,
  "total" : 1
}

8.2. 단일 게시판 조회

8.2.1. 요청 예시

GET /boards/813bb2eb-60a8-4573-afff-2993c8a9643e HTTP/1.1
Host: localhost:8080

8.2.2. 응답 필드

경로 타입 설명

id

String

게시판 글 ID

exhibitionId

String

전시 ID

title

String

제목

content

String

내용

attachmentMediaIds

Array

첨부 미디어 ID 목록

attachmentMedias

Array

첨부 미디어 목록

attachmentMedias[].id

String

첨부 미디어 ID

attachmentMedias[].fileName

String

첨부 미디어 파일명

authorUserId

String

작성자 사용자 ID

createdAt

String

생성 일시

updatedAt

String

수정 일시

8.2.3. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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: 500

{
  "id" : "813bb2eb-60a8-4573-afff-2993c8a9643e",
  "exhibitionId" : "0441b2a4-3a34-461d-b8ac-9d164f3dbe40",
  "title" : "공지",
  "content" : "안내 내용",
  "attachmentMediaIds" : [ "b945a00a-2d78-449b-a6cc-8ca39cdbc564" ],
  "attachmentMedias" : [ {
    "id" : "a3759a33-1bfc-4031-8cea-f24c1a7af6a9",
    "fileName" : "notice.pdf"
  } ],
  "authorUserId" : "57ec3743-1c73-4e4f-bb82-57cd3f88208f",
  "createdAt" : "2026-04-16T00:18:04.708542Z",
  "updatedAt" : "2026-04-16T00:18:04.708542Z"
}

8.2.4. 응답 본문(JSON)

{
  "id" : "813bb2eb-60a8-4573-afff-2993c8a9643e",
  "exhibitionId" : "0441b2a4-3a34-461d-b8ac-9d164f3dbe40",
  "title" : "공지",
  "content" : "안내 내용",
  "attachmentMediaIds" : [ "b945a00a-2d78-449b-a6cc-8ca39cdbc564" ],
  "attachmentMedias" : [ {
    "id" : "a3759a33-1bfc-4031-8cea-f24c1a7af6a9",
    "fileName" : "notice.pdf"
  } ],
  "authorUserId" : "57ec3743-1c73-4e4f-bb82-57cd3f88208f",
  "createdAt" : "2026-04-16T00:18:04.708542Z",
  "updatedAt" : "2026-04-16T00:18:04.708542Z"
}

9. 미디어(Media)

9.1. 미디어 파일 다운로드

9.1.1. 요청 예시

GET /media/536f88a7-15b9-47c1-8dd2-5df3eb0e5cf1 HTTP/1.1
Host: localhost:8080

9.1.2. 응답 항목(헤더)

Name Description

Content-Type

미디어 MIME 타입

Content-Length

파일 바이트 크기

9.1.3. 응답 예시

HTTP/1.1 200 OK
Cache-Control: public, max-age=31536000, immutable
Content-Type: image/jpeg
Content-Length: 3
Accept-Ranges: bytes
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
X-Frame-Options: DENY



9.1.4. 응답 본문(바이너리)



10. 사용자(User)

10.1. 내 정보 조회

10.1.1. 요청 헤더

Name Description

Authorization

Bearer Access Token

10.1.2. 요청 예시

GET /users/me HTTP/1.1
Authorization: Bearer {accessToken}
Host: localhost:8080

10.1.3. 응답 필드

경로 타입 설명

name

String

이름

role

String

사용자 권한

email

String

이메일

department

String

소속

phoneNumber

String

연락처

studentNumber

String

학번

registrationCompleted

Boolean

회원가입 정보 입력 완료 여부

10.1.4. 응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
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

{
  "name" : "홍길동",
  "role" : "STUDENT",
  "email" : "hong@example.com",
  "department" : "소프트웨어학과",
  "phoneNumber" : "010-1234-5678",
  "studentNumber" : "2020123456",
  "registrationCompleted" : true
}

10.1.5. 응답 본문(JSON)

{
  "name" : "홍길동",
  "role" : "STUDENT",
  "email" : "hong@example.com",
  "department" : "소프트웨어학과",
  "phoneNumber" : "010-1234-5678",
  "studentNumber" : "2020123456",
  "registrationCompleted" : true
}