Docs : 동아리 목록, 즐겨찾기 목록, 소속 목록, 상세 조회 API 설계

.spectral.yaml

@@ -0,0 +1,2 @@
+extends:
+  - spectral:oas

components/schemas/club/ClubBuilding.yaml

@@ -0,0 +1,14 @@
+type: string
+description: |
+  동아리 위치의 건물명.
+
+  **값 형식:**
+  - 클라이언트/서버 API 통신에서는 building 값을 snake_case로 사용합니다.
+  - 서버 내부 데이터는 필요 시 별도 매핑을 통해 관리할 수 있습니다.
+
+  가능한 값:
+  - sanghuh_library: 상허도서관 / Sanghuh Library
+  - etc: 기타 / Other or unspecified building
+enum:
+  - sanghuh_library
+  - etc

components/schemas/club/ClubCategory.yaml

@@ -0,0 +1,19 @@
+type: string
+description: |
+  동아리 카테고리 (활동 성격).
+
+  **값 형식:**
+  - 서버 내부 데이터는 UPPERCASE로 저장/관리됩니다 (예: ACADEMIC, ACTIVITY)
+  - 클라이언트와의 API 통신 시에는 lowercase로 변환하여 사용합니다 (예: academic, activity)
+  - API 요청/응답에서 category 필드는 lowercase 값을 사용합니다. (즉, 이 enum은 lowercase 값 기준)
+
+  가능한 카테고리 값 (lowercase 기준):
+  - academic: 학술활동 / Academic and study-oriented club activities
+  - culture_art: 문화예술 / Culture, arts, performance, and creative activities
+  - social_value: 사회가치 / Social contribution and volunteering activities
+  - activity: 야외활동 / Sports, leisure, and outdoor activities
+enum:
+  - academic
+  - culture_art
+  - social_value
+  - activity

components/schemas/club/ClubDetailResponse.yaml

@@ -4,24 +4,25 @@ examples:
   - id: 1
     name: 리드미
     summary: '단순히 책만 읽는 독서모임이 아닌, 책 속에 빠져 인사이트를 나누는 모임'
-    category: null
-    affiliation: CENTRAL
-    division: string
-    isSubscribed: true
+    category: academic
+    division: central
     subscriberCount: 128
-    instagramUrl: 'https://instagram.com/kuring.official'
+    isSubscribed: true
+    homepageUrl: 'https://instagram.com/kuring.official'
     description: 저희 리드미는 2020년부터 시작된...
     qualifications: |-
       건국대학교 재학생 및 휴학생 누구나
       (매주 목요일 활동 가능하신 분)
-    isRecruiting: true
+    recruitmentStatus: recruiting
     recruitStartAt: '2026-03-02T00:00:00'
     recruitEndAt: '2026-03-15T23:59:59'
     applyUrl: 'https://forms.gle/xyz...'
-    descriptionImageUrl: string
+    posterImageUrl: 'https://api.kuring.com/images/club_poster_readme.png'
     location:
-      building: string
-      room: string
+      building: sanghuh_library
+      room: "101"
+      lon: 127.074
+      lat: 37.541
 properties:
   id:
     type: integer
@@ -43,40 +44,28 @@ properties:
   # [2] 배지 및 태그 정보
   # ----------------------------------------
   category:
-    type: string
-    description: 동아리카테고리
-  affiliation:
-    type: string
-    description: |
-      소속 구분 (배지 표시용)
-      * `CENTRAL`: 중앙동아리
-      * `COLLEGE`: 단과대 소모임
-    enum:
-      - CENTRAL
-      - COLLEGE
-    example: CENTRAL
+    $ref: ./ClubCategory.yaml
+    description: 동아리 카테고리
   division:
-    description: |
-      구체적인 소속 부서/단과대명
-      (affiliation이 CENTRAL이면 분과명, COLLEGE면 단과대명)
-    type: string
+    $ref: ./ClubDivision.yaml
+    description: 동아리 소속 (단과대·학과·연합 등)
   # ----------------------------------------
-  # [3] 메타 데이터 (좋아요/구독)
+  # [3] 메타 데이터 (구독)
   # ----------------------------------------
-  isSubscribed:
-    type: boolean
-    description: 현재 사용자의 구독/즐겨찾기 여부 (별 아이콘 채움 여부)
-    example: true
   subscriberCount:
     type: integer
-    description: '총 구독자 수 ({n}+)'
+    description: 동아리 구독자 수
     example: 128
+  isSubscribed:
+    type: boolean
+    description: 현재 사용자의 동아리 구독 여부 (비로그인 시 false)
+    example: true
   # ----------------------------------------
   # [4] 링크 및 위치 정보 (하이퍼링크)
   # ----------------------------------------
-  instagramUrl:
+  homepageUrl:
     type: string
-    description: 인스타그램 프로필 링크 (없으면 null)
+    description: 동아리 홈페이지/채널 URL (인스타, 네이버 카페 등, 없으면 null). URL에 따라 클라이언트에서 아이콘 분기.
     example: 'https://instagram.com/kuring.official'
   # ----------------------------------------
   # [5] 상세 내용
@@ -94,10 +83,9 @@ properties:
   # ----------------------------------------
   # [6] 모집 관련 정보
   # ----------------------------------------
-  isRecruiting:
-    type: boolean
-    description: 현재 모집 중 여부 (D-day 배지 계산용)
-    example: true
+  recruitmentStatus:
+    $ref: ./ClubRecruitmentStatus.yaml
+    description: 모집 상태 (모집전/모집중/모집완료/상시모집)
   recruitStartAt:
     type: string
     format: date-time
@@ -112,26 +100,10 @@ properties:
     type: string
     description: 지원하기 버튼 클릭 시 이동할 구글폼 URL
     example: 'https://forms.gle/xyz...'
-  descriptionImageUrl:
+  posterImageUrl:
     type: string
-    description: |
-      본문에 포함될 홍보 이미지/포스터 URL 목록
-      (첫 번째 이미지가 대표 썸네일로 사용될 수 있음)
-    x-stoplight:
-      id: tfxf5822txk09
+    description: 동아리 포스터 이미지 URL (없으면 null)
+    nullable: true
   location:
-    type: object
-    x-stoplight:
-      id: xu4s7c5plrq8q
     description: 동아리 위치 정보
-    properties:
-      building:
-        type: string
-        x-stoplight:
-          id: hafkb0pl5w0e5
-        description: 동아리방 건물
-      room:
-        type: string
-        x-stoplight:
-          id: x0lkhthhf4gy5
-        description: 동아리 방 호수
+    $ref: ./ClubLocationDto.yaml

components/schemas/club/ClubDivision.yaml

@@ -0,0 +1,51 @@
+type: string
+description: |
+  동아리 소속 (단과대·학과·연합 등).
+
+  **값 형식:**
+  - 서버 내부 데이터는 UPPERCASE로 저장/관리됩니다 (예: CENTRAL, ENGINEERING)
+  - 클라이언트와의 API 통신 시에는 lowercase로 변환하여 사용합니다 (예: central, engineering)
+  - API 요청/응답에서 division 필드는 lowercase 값을 사용합니다. (즉, 이 enum은 lowercase 값 기준)
+
+  가능한 소속 값 (lowercase 기준):
+  - central: 중앙 / Central organization under the university
+  - liberal_arts: 문과대학 / College of Liberal Arts
+  - science: 이과대학 / College of Science
+  - architecture: 건축대학 / College of Architecture
+  - engineering: 공과대학 / College of Engineering
+  - social_sciences: 사회과학대학 / College of Social Sciences
+  - business: 경영대학 / College of Business Administration
+  - real_estate: 부동산과학원 / College of Real Estate
+  - ku_convergence: KU융합과학기술원 / Konkuk Institute of Technology
+  - sanghuh_life_science: 상허생명과학대학 / College of Sang-Huh Life Science
+  - veterinary: 수의과대학 / College of Veterinary Medicine
+  - art_design: 예술디자인대학 / College of Art & Design
+  - education: 사범대학 / College of Education
+  - sanghuh_general: 상허교양대학 / Sang-Huh College
+  - international: 국제대학 / International College
+  - convergence_sci_tech: 융합과학기술원 / Institute of Technology
+  - life_science: 생명과학대학 / College of Life Science
+  - computer_science: 컴퓨터공학과 / Department of Computer Science
+  - mechanical_engineering: 기계공학과 / Department of Mechanical Engineering
+  - etc: 기타 / Other or unspecified affiliation
+enum:
+  - central
+  - liberal_arts
+  - science
+  - architecture
+  - engineering
+  - social_sciences
+  - business
+  - real_estate
+  - ku_convergence
+  - sanghuh_life_science
+  - veterinary
+  - art_design
+  - education
+  - sanghuh_general
+  - international
+  - convergence_sci_tech
+  - life_science
+  - computer_science
+  - mechanical_engineering
+  - etc

components/schemas/club/ClubDivisionListItem.yaml

@@ -0,0 +1,11 @@
+type: object
+description: 동아리 소속(division) 목록 한 건. 클라이언트 필터/드롭다운용.
+properties:
+  code:
+    type: string
+    description: 소속 코드 (API 필터/요청 시 사용, lowercase)
+    example: central
+  koreanName:
+    type: string
+    description: 한글 표기명
+    example: 중앙

components/schemas/club/ClubDivisionListResponse.yaml

@@ -0,0 +1,8 @@
+type: object
+description: 동아리 소속(division) 목록 응답의 data 필드. 가변적으로 변할 수 있어 API로 제공합니다.
+properties:
+  divisions:
+    type: array
+    items:
+      $ref: ./ClubDivisionListItem.yaml
+    description: 현재 서버에서 지원하는 소속 목록 (0개 이상)

components/schemas/club/ClubListItemDto.yaml

@@ -0,0 +1,45 @@
+type: object
+description: 동아리 목록/즐겨찾기 목록 공통 항목 (한 건)
+properties:
+  id:
+    type: integer
+    description: 동아리 ID
+    example: 1
+  name:
+    type: string
+    description: 동아리 명
+    example: Kuring
+  summary:
+    type: string
+    description: 동아리 요약 (한 줄 소개)
+    example: 건국대학교 공지사항 알림 서비스 개발 동아리
+  iconImageUrl:
+    type: string
+    description: 동아리 아이콘 이미지 URL
+    example: 'https://api.kuring.com/images/club_icon.png'
+  category:
+    $ref: ./ClubCategory.yaml
+    description: 동아리 카테고리
+  division:
+    $ref: ./ClubDivision.yaml
+    description: 동아리 소속 (단과대·학과·연합 등)
+  isSubscribed:
+    type: boolean
+    description: 현재 사용자의 동아리 구독 여부 (비로그인 시 false)
+    example: false
+  subscriberCount:
+    type: integer
+    description: 동아리 구독자 수
+    example: 19
+  recruitStartDate:
+    type: string
+    format: date-time
+    description: 동아리 모집 시작일
+    example: '2026-05-01T00:00:00'
+    nullable: true
+  recruitEndDate:
+    type: string
+    format: date-time
+    description: 동아리 모집 마감일
+    example: '2026-06-03T23:59:59'
+    nullable: true

components/schemas/club/ClubListResponse.yaml

@@ -0,0 +1,22 @@
+type: object
+description: 응답의 data 필드. data 안에 clubs(배열), cursor, hasNext, totalCount를 담습니다.
+properties:
+  clubs:
+    type: array
+    items:
+      $ref: ./ClubListItemDto.yaml
+    description: 동아리 목록 (한 페이지 분)
+  cursor:
+    type: integer
+    format: int64
+    nullable: true
+    description: 다음 페이지 요청 시 사용할 커서 (다음 페이지 없으면 null)
+  hasNext:
+    type: boolean
+    description: 다음 페이지 존재 여부
+  totalCount:
+    type: integer
+    description: |
+      총 개수.
+      - 목록 조회: 필터 조건에 맞는 전체 동아리 개수
+      - 즐겨찾기 목록 조회: 사용자가 즐겨찾기한 동아리 전체 개수

components/schemas/club/ClubLocationDto.yaml

@@ -0,0 +1,22 @@
+type: object
+description: 동아리 위치 정보
+properties:
+  building:
+    $ref: ./ClubBuilding.yaml
+    description: 동아리방 건물 (snake_case)
+  room:
+    type: string
+    description: 동아리 방 호수
+    example: "101"
+  lon:
+    type: number
+    format: double
+    description: 경도 (longitude, WGS84). 지도 마커용. 미제공 시 null
+    nullable: true
+    example: 127.074
+  lat:
+    type: number
+    format: double
+    description: 위도 (latitude, WGS84). 지도 마커용. 미제공 시 null
+    nullable: true
+    example: 37.541

components/schemas/club/ClubRecruitmentStatus.yaml

@@ -0,0 +1,19 @@
+type: string
+description: |
+  동아리 모집 상태.
+
+  **값 형식:**
+  - 서버 내부 데이터는 UPPERCASE로 저장/관리됩니다 (예: RECRUITING)
+  - 클라이언트와의 API 통신 시에는 lowercase로 변환하여 사용합니다 (예: recruiting)
+  - API 요청/응답에서 recruitmentStatus 필드는 lowercase 값을 사용합니다. (즉, 이 enum은 lowercase 값 기준)
+
+  가능한 상태 값 (lowercase 기준):
+  - before: 모집전 / Recruitment has not started yet
+  - recruiting: 모집중 / Recruitment is currently open
+  - closed: 모집 완료 / Recruitment has ended
+  - always: 상시 모집 / Always open recruitment
+enum:
+  - before
+  - recruiting
+  - closed
+  - always

components/schemas/club/ClubResponse.yaml

@@ -13,9 +13,8 @@ properties:
     description: 동아리 한줄 소개
     example: 건국대학교 공지사항 알림 서비스 개발 동아리
   category:
-    type: string
+    $ref: ./ClubCategory.yaml
     description: 카테고리
-    example: OUTDOOR
   thumbnailUrl:
     type: string
     description: 썸네일 이미지 URL
@@ -24,11 +23,11 @@ properties:
     type: boolean
     description: '사용자의 구독 여부 (True: 구독중)'
     example: false
-  bookmarkCount:
+  subscriberCount:
     type: integer
     x-stoplight:
       id: iosvd3nzwj77q
-    description: 즐겨찾기 수
+    description: 동아리 구독자 수
     example: 19
   recuritEndDate:
     type: string
@@ -37,8 +36,5 @@ properties:
     example: '2026-06-03T12:18:00.00000'
     description: 공고 마감일
   division:
-    type: string
-    x-stoplight:
-      id: 9bk3s4xaz2uea
-    description: 소속
-    example: CENTRAL
+    $ref: ./ClubDivision.yaml
+    description: 동아리 소속