openapi.yaml

openapi: 3.0.1
info:
  title: Kuring API
  version: v2
  description: "### \U0001F393 건국대 공지사항 알림 서비스 '쿠링'의 공식 API 명세서입니다.    \n이 문서는 **Kuring 프로젝트**의 백엔드 기능을 정의합니다. \n\n* **담당자**: 쿠링 팀 (kuring.korea@gmail.com)\n* **문서 업데이트**: 2026-01-21"
  contact:
    name: Github
    url: 'https://github.com/ku-ring'
    email: kuring.korea@gmail.com
  termsOfService: 'https://github.com/ku-ring'
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
# 1. 보안 설정 및 공통 파라미터 (Try it / 문서 도구에서 헤더·인증 입력란 노출용)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT 액세스 토큰 (로그인 후 발급)
  parameters:
    UserTokenHeaderRequired:
      name: User-Token
      in: header
      required: true
      schema:
        type: string
      description: FCM 기반 사용자 기기 식별 토큰
      example: '1234'
    UserTokenHeaderOptional:
      name: User-Token
      in: header
      required: false
      schema:
        type: string
      description: FCM 기반 사용자 기기 식별 토큰
      example: '1234'
  responses:
    UnauthorizedJwt:
      description: 인증 실패 (JWT 만료/없음/유효하지 않음)
      content:
        application/json:
          schema:
            $ref: ./components/schemas/common/ErrorResponse.yaml
          example:
            isSuccess: false
            resultCode: 401
            resultMsg: 유효하지 않거나 만료된 토큰입니다.
    BadRequestUserToken:
      description: 잘못된 요청 (User-Token 누락/형식 오류 등)
      content:
        application/json:
          schema:
            $ref: ./components/schemas/common/ErrorResponse.yaml
          example:
            isSuccess: false
            resultCode: 400
            resultMsg: User-Token이 필요하거나 올바르지 않습니다.
tags:
  - name: Academic
    description: 학사일정 API
  - name: Admin
    description: 관리자 전용 API
  - name: AI
    description: AI 챗봇 API
  - name: Club
    description: 교내 동아리 정보 조회 및 관리 API
  - name: Deprecated
    description: ⚠️ 곧 삭제될 예정인 API입니다. 신규 개발 시 사용을 지양하세요.
  - name: Draft
    description: 설계 초안 단계입니다. 실제 호출이 불가능하거나 구조가 변경될 수 있습니다.
  - name: Notice
    description: 공지사항 관련 API
  - name: Report
    description: 신고 기능 API
  - name: Staff
    description: 교직원 검색 API
  - name: User
    description: 사용자 관련 API
  - name: Verification
    description: 이메일 인증 API
# 2. API 경로 정의
paths:
  # ------------------------------------------------------------------
  # [로그인/인증]
  # ------------------------------------------------------------------
  /api/v2/users/login:
    post:
      tags:
        - User
      summary: 사용자 로그인
      description: 사용자가 이메일과 비밀번호로 로그인하여 액세스 토큰을 발급받습니다.
      operationId: login
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserLoginRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
                  password: '1234'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/user/UserLoginResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 로그인되었습니다.
                    data:
                      accessToken: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ...
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  /api/v2/users/logout:
    post:
      tags:
        - User
      summary: 사용자 로그아웃
      description: 현재 로그인된 사용자의 세션을 만료시키고 토큰을 무효화합니다.
      operationId: logout
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 로그아웃되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/users/signup:
    post:
      tags:
        - User
      summary: 사용자 회원가입
      description: FCM 디바이스 토큰을 포함하여 새로운 사용자를 회원가입 처리합니다.
      operationId: signup
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserSignupRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
                  password: '1234'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 회원가입이 완료되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  /api/v2/users/withdraw:
    delete:
      tags:
        - User
      summary: 사용자 회원 탈퇴
      description: 로그인된 사용자의 계정을 삭제하고 모든 관련 데이터를 정리합니다.
      operationId: withdraw
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 탈퇴가 완료되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/users/password:
    patch:
      tags:
        - User
      summary: 사용자 비밀번호 변경
      description: 로그인된 사용자가 비밀번호를 새 값으로 변경합니다.
      operationId: modifyPassword
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserPasswordModifyRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
                  password: '5678'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 비밀번호가 변경되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  # ------------------------------------------------------------------
  # [사용자 정보]
  # ------------------------------------------------------------------
  /api/v2/users/user-me:
    get:
      tags:
        - User
      summary: 사용자 정보 조회
      description: 현재 로그인된 사용자의 프로필 정보를 조회합니다.
      operationId: lookupUserInfo
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/user/UserInfoResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      email: kuring@konkuk.ac.kr
                      nickname: 쿠링이
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/users/ask-counts:
    get:
      tags:
        - User
      summary: 사용자 질문 가능횟수 조회
      description: 오늘 남은 AI 질문 횟수와 하루 최대 질문 가능 횟수를 조회합니다.
      operationId: lookupUserAIAskCount
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderOptional'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/user/UserAIAskCountResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      leftAskCount: 3
                      maxAskCount: 10
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  # ------------------------------------------------------------------
  # [구독 및 알림]
  # ------------------------------------------------------------------
  /api/v2/users/subscriptions/departments:
    get:
      tags:
        - User
      summary: 사용자 학과 조회
      description: 사용자가 구독 중인 학과 목록을 조회합니다.
      operationId: lookupUserSubscribeDepartments
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/user/UserDepartmentNameResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - name: computer_cse
                        hostPrefix: cse
                        korName: 컴퓨터공학부
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
    post:
      tags:
        - User
      summary: 사용자 학과 수정
      description: 사용자가 구독할 학과 목록을 추가·수정합니다.
      operationId: editUserSubscribeDepartments
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserDepartmentsSubscribeRequest.yaml
            examples:
              Success:
                value:
                  departments:
                    - computer_cse
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 학과 구독이 수정되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  /api/v2/users/subscriptions/categories:
    get:
      tags:
        - User
      summary: 사용자 카테고리 조회
      description: 사용자가 구독 중인 공지 카테고리 목록을 조회합니다.
      operationId: lookupUserSubscribeCategories
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/user/UserCategoryNameResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - name: bachelor
                        hostPrefix: bachelor
                        korName: 학사
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
    post:
      tags:
        - User
      summary: 사용자 카테고리 수정
      description: 사용자가 구독할 공지 카테고리 목록을 추가·수정합니다.
      operationId: editUserSubscribeCategories
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserCategoriesSubscribeRequest.yaml
            examples:
              Success:
                value:
                  categories:
                    - bachelor
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 카테고리 구독이 수정되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  /api/v2/users/notifications/academic-events:
    patch:
      tags:
        - User
      summary: 사용자 학사일정 알림 설정 수정
      description: 사용자의 학사일정 알림 활성화 여부를 변경합니다.
      operationId: updateAcademicEventNotification
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserAcademicEventNotificationRequest.yaml
            examples:
              Success:
                value:
                  enabled: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 학사일정 알림 설정이 변경되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  # ------------------------------------------------------------------
  # [기타 기능]
  # ------------------------------------------------------------------
  /api/v2/users/feedbacks:
    post:
      tags:
        - User
      summary: 사용자 피드백 작성
      description: 앱 사용성이나 오류 등에 대한 사용자의 피드백을 서버에 전송합니다.
      operationId: saveFeedback
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserFeedbackRequest.yaml
            examples:
              Success:
                value:
                  content: 테스트 피드백 내용
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 피드백이 접수되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  /api/v2/users/bookmarks:
    get:
      tags:
        - User
      summary: 사용자 북마크 조회
      description: 사용자가 저장해 둔 공지사항 북마크 목록을 조회합니다.
      operationId: lookupUserBookmarks
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/user/UserBookmarkResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - articleId: '51234'
                        postedDate: '2023-10-25'
                        subject: 2023학년도 2학기 수강신청 안내
                        category: bachelor
                        baseUrl: 'https://www.konkuk.ac.kr/do/MessageBoard/...'
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
    post:
      tags:
        - User
      summary: 사용자 북마크 작성
      description: 특정 공지사항을 북마크에 추가합니다.
      operationId: saveBookmark
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/user/UserBookmarkRequest.yaml
            examples:
              Success:
                value:
                  articleId: '1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 북마크가 추가되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  # ------------------------------------------------------------------
  # [공지사항] Notice
  # ------------------------------------------------------------------
  /api/v2/notices:
    get:
      tags:
        - Notice
      summary: 공지사항 목록 조회
      description: 특정 학과나 카테고리의 공지사항 목록을 조회합니다.
      operationId: getNotices
      parameters:
        - name: type
          in: query
          description: '조회 타입 (school=학교공지, dep=학과공지)'
          required: true
          schema:
            type: string
            enum:
              - school
              - dep
            example: dep
        - name: department
          in: query
          description: 학과 코드 (type이 dep일 때 필수)
          schema:
            type: string
            example: computer_cse
        - name: category
          in: query
          description: 카테고리 (type이 school일 때 필수)
          schema:
            type: string
            example: bachelor
        - name: page
          in: query
          description: 페이지 번호 (0부터 시작)
          schema:
            type: integer
            default: 0
            example: 0
        - name: size
          in: query
          description: 페이지 크기
          schema:
            type: integer
            default: 10
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/notice/NoticeListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      notices:
                        - articleId: '56281'
                          postedDate: '2023-10-31'
                          subject: '[학사] 2024학년도 1학기 전과 신청 안내'
                          category: bachelor
                          important: true
                          baseUrl: 'https://www.konkuk.ac.kr/do/MessageBoard/ArticleRead.do?id=56281'
  /api/v2/notices/search:
    get:
      tags:
        - Notice
      summary: 공지사항 키워드 검색
      description: 키워드를 기준으로 학교 및 학과 공지사항을 검색합니다.
      operationId: searchNotices
      parameters:
        - name: content
          in: query
          description: 검색할 키워드 (공백으로 구분)
          required: true
          schema:
            type: string
            example: 장학금
        - name: page
          in: query
          description: 결과 페이지 번호 (0부터 시작)
          schema:
            type: integer
            default: 0
            example: 0
        - name: size
          in: query
          description: 한 페이지에 포함될 결과 개수
          schema:
            type: integer
            default: 10
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/notice/NoticeListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      notices:
                        - articleId: '56281'
                          postedDate: '2023-10-31'
                          subject: '[학사] 2024학년도 1학기 전과 신청 안내'
                          category: bachelor
                          important: true
                          baseUrl: 'https://www.konkuk.ac.kr/do/MessageBoard/ArticleRead.do?id=56281'
  /api/v2/notices/departments:
    get:
      tags:
        - Notice
      summary: 공지 조회 지원 학과 목록
      description: 공지 조회 기능이 지원되는 학과 목록을 조회합니다.
      operationId: getNoticeDepartments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/notice/NoticeDepartmentListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      departments:
                        - name: computer_cse
                          korName: 컴퓨터공학부
  /api/v2/notices/categories:
    get:
      tags:
        - Notice
      summary: 공지 조회 지원 카테고리 목록
      description: 공지 조회 기능이 지원되는 카테고리 목록을 조회합니다.
      operationId: getNoticeCategories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/notice/NoticeCategoryListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      categories:
                        - bachelor
                        - scholarship
                      # ------------------------------------------------------------------
                      # [공지사항 댓글] Notice Comments
                      # ------------------------------------------------------------------
  '/api/v2/notices/{articleId}/comments':
    get:
      tags:
        - Notice
      summary: 공지사항 댓글 조회
      description: 특정 공지에 추가된 모든 댓글을 커서 페이징으로 조회합니다.
      operationId: getNoticeComments
      parameters:
        - name: articleId
          in: path
          required: true
          description: 공지 ID (게시글 ID)
          schema:
            type: string
            example: '1'
        - name: cursor
          in: query
          description: 다음 페이지 요청 시 사용할 커서 (최초 요청 시 생략)
          required: false
          schema:
            type: string
        - name: size
          in: query
          description: '단일 요청의 사이즈, 1 ~ 30까지 허용'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 30
            default: 10
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          list:
                            type: array
                            items:
                              $ref: ./components/schemas/notice/NoticeCommentDto.yaml
                            description: 댓글 목록
                          cursor:
                            type: string
                            nullable: true
                            description: 다음 페이지 요청 시 사용할 커서 (다음 페이지 없으면 null)
                          hasNext:
                            type: boolean
                            description: 다음 페이지 존재 여부
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      list:
                        - id: comment_123
                          content: 전과 신청 기간은 공지 본문을 확인해주세요.
                          createdAt: '2024-01-21T09:00:00Z'
                      cursor: eyJpZCI6MTIzfQ
                      hasNext: false
    post:
      tags:
        - Notice
      summary: 공지사항 댓글 작성
      description: 특정 공지사항에 새로운 댓글을 작성합니다.
      operationId: createNoticeComment
      parameters:
        - name: articleId
          in: path
          description: 댓글을 작성할 공지사항의 ID
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/notice/NoticeCommentRequest.yaml
            examples:
              Success:
                value:
                  content: 댓글 내용
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 댓글이 등록되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  '/api/v2/notices/{articleId}/comments/{commentId}':
    post:
      tags:
        - Notice
      summary: 공지사항 댓글 수정
      description: '주의: REST 표준(PATCH)이 아닌 POST 메서드를 사용합니다.'
      operationId: updateNoticeComment
      parameters:
        - name: articleId
          in: path
          description: 댓글이 속한 공지사항의 ID
          required: true
          schema:
            type: string
        - name: commentId
          in: path
          required: true
          description: 수정할 댓글 ID
          schema:
            type: string
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/notice/NoticeCommentRequest.yaml
            examples:
              Success:
                value:
                  content: 수정한 댓글 내용
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 댓글이 수정되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
    delete:
      tags:
        - Notice
      summary: 공지사항 댓글 삭제
      description: 특정 공지사항에 달린 댓글을 삭제합니다.
      operationId: deleteNoticeComment
      parameters:
        - name: articleId
          in: path
          description: 댓글이 속한 공지사항의 ID
          required: true
          schema:
            type: string
        - name: commentId
          in: path
          description: 삭제할 댓글 ID
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 댓글이 삭제되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  # ------------------------------------------------------------------
  # [관리자] Admin
  # ------------------------------------------------------------------
  /api/v2/admin/notices/prod:
    post:
      tags:
        - Admin
      summary: 실제 공지사항 전송 (Prod)
      description: 앱 사용자 전체에게 푸시 알림과 함께 공지를 등록합니다.
      operationId: createProdNotice
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/admin/AdminRealNoticeRequest.yaml
            examples:
              Success:
                value:
                  title: 서버 점검 안내
                  body: 오늘 23시부터 24시까지 서버 점검이 진행됩니다.
                  url: https://kuring.com/notices/1234
                  adminPassword: admin-password
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 공지가 전송되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/notices/dev:
    post:
      tags:
        - Admin
      summary: 테스트 공지사항 전송 (Dev)
      description: 개발 서버 혹은 테스터에게만 공지를 전송합니다.
      operationId: createDevNotice
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/admin/AdminTestNoticeRequest.yaml
            examples:
              Success:
                value:
                  category: bachelor
                  subject: 테스트 공지입니다
                  noticeId: "1234"
                  articleId: "1234"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 테스트 공지가 전송되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/users/subscriptions/all:
    post:
      tags:
        - Admin
      summary: 사용자 전체 재구독 처리
      description: 모든 사용자의 구독 정보를 갱신합니다. (비상용)
      operationId: refreshAllSubscriptions
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 전체 구독이 갱신되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/alerts:
    get:
      tags:
        - Admin
      summary: 예약 알림 목록 조회
      description: 관리자가 등록한 예약 알림 목록을 페이지 단위로 조회합니다.
      operationId: getAdminAlerts
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: 페이지
          required: true
          schema:
            minimum: 0
            type: integer
            format: int32
            example: 0
        - name: size
          in: query
          description: '단일 페이지의 사이즈, 1 ~ 30까지 허용'
          required: true
          schema:
            maximum: 30
            minimum: 1
            type: integer
            format: int32
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/admin/AdminAlertDto.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - id: alert_999
                        title: 수강신청 10분 전입니다!
                        message: 잊지 말고 준비하세요.
                        reservedTime: '2024-02-15T09:50:00'
                        status: PENDING
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
    post:
      tags:
        - Admin
      summary: 예약 알림 등록
      description: 지정한 시간에 발송될 새로운 예약 알림을 등록합니다.
      operationId: createAdminAlert
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/admin/AdminAlertRequest.yaml
            examples:
              Success:
                value:
                  title: 알림 제목
                  message: 알림 내용
                  reservedTime: '2024-04-20T12:00:00'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 예약 알림이 등록되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  '/api/v2/admin/alerts/{id}':
    delete:
      tags:
        - Admin
      summary: 예약 알림 취소/삭제
      description: 특정 예약 알림을 취소하거나 삭제합니다.
      operationId: deleteAdminAlert
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          description: 취소 또는 삭제할 예약 알림 ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 예약 알림이 삭제되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/whitelist-words/reload:
    post:
      tags:
        - Admin
      summary: 허용 단어 사전 리로드
      description: 서버에 저장된 허용 단어 사전을 다시 로드하여 필터링에 반영합니다.
      operationId: reloadWhitelist
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 허용 단어 사전이 갱신되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/badwords/reload:
    post:
      tags:
        - Admin
      summary: 금칙어 사전 리로드
      description: 서버에 저장된 금칙어 사전을 다시 로드하여 필터링에 반영합니다.
      operationId: reloadBadwords
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 금칙어 사전이 갱신되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/reports:
    get:
      tags:
        - Admin
      summary: 신고 목록 조회
      description: 사용자가 등록한 신고 내역을 페이지 단위로 조회합니다.
      operationId: getReports
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: 페이지
          required: true
          schema:
            minimum: 0
            type: integer
            format: int32
            example: 0
        - name: size
          in: query
          description: '단일 페이지의 사이즈, 1 ~ 30까지 허용'
          required: true
          schema:
            maximum: 30
            minimum: 1
            type: integer
            format: int32
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/admin/AdminReportResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data: []
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/feedbacks:
    get:
      tags:
        - Admin
      summary: 피드백 목록 조회
      description: 사용자 피드백 내역을 페이지 단위로 조회합니다.
      operationId: getFeedbacks
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: 페이지
          required: true
          schema:
            minimum: 0
            type: integer
            format: int32
            example: 0
        - name: size
          in: query
          description: '단일 페이지의 사이즈, 1 ~ 30까지 허용'
          required: true
          schema:
            maximum: 30
            minimum: 1
            type: integer
            format: int32
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/admin/AdminFeedbackResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data: []
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/embedding:
    post:
      tags:
        - Admin
      summary: 데이터 임베딩 실행
      description: 최신 공지사항이나 학사 정보를 AI 검색용 데이터로 변환합니다.
      operationId: runEmbedding
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 임베딩이 완료되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/admin/academic/dev:
    post:
      tags:
        - Admin
      summary: 테스트 학사일정 알림 전송 (Dev)
      description: 개발 서버 환경에서 학사일정 푸시 알림을 테스트합니다.
      operationId: sendDevAcademicAlert
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/admin/AdminAcademicTestNotificationRequest.yaml
            examples:
              Success:
                value:
                  title: 개강
                  body: 오늘은 개강 일정이 있어요.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 테스트 알림이 전송되었습니다.
                    data: null
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  # ------------------------------------------------------------------
  # [인증] Verification
  # ------------------------------------------------------------------
  /api/v2/verification-code/signup:
    post:
      tags:
        - Verification
      summary: 회원가입용 인증번호 발송
      description: 회원가입을 위해 사용자의 이메일로 인증번호를 발송합니다.
      operationId: sendSignupCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/verification/VerificationCodeRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 인증번호가 발송되었습니다.
                    data: null
  /api/v2/verification-code/password-reset:
    post:
      tags:
        - Verification
      summary: 비밀번호 재설정용 인증번호 발송
      description: 비밀번호 재설정을 위해 사용자의 이메일로 인증번호를 발송합니다.
      operationId: sendPasswordResetCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/verification/VerificationCodeRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 인증번호가 발송되었습니다.
                    data: null
  /api/v2/verification-code/verify:
    post:
      tags:
        - Verification
      summary: 인증번호 검증
      description: 이메일로 발송된 인증번호를 검증하여 요청을 승인합니다.
      operationId: verifyCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/verification/VerificationCheckRequest.yaml
            examples:
              Success:
                value:
                  email: user@konkuk.ac.kr
                  code: '123456'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 인증이 완료되었습니다.
                    data: null
  # ------------------------------------------------------------------
  # [교직원] Staff
  # ------------------------------------------------------------------
  /api/v2/staffs/search:
    get:
      tags:
        - Staff
      summary: 교직원 검색
      description: 교직원의 이름이나 학과를 기준으로 검색합니다.
      operationId: searchStaffs
      parameters:
        - name: content
          in: query
          description: '검색어 (이름, 학과 등)'
          required: true
          schema:
            type: string
            example: 홍길동
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/staff/StaffResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - name: 김건국
                        major: 컴퓨터공학부
                        lab: 공학관 123호
                        phone: 02-450-1234
                        email: kimkk@konkuk.ac.kr
                        dept: 공과대학
                    # ------------------------------------------------------------------
                    # [AI] Chatbot
                    # ------------------------------------------------------------------
  /api/v2/ai/messages:
    get:
      tags:
        - AI
      summary: AI에게 질문하기
      description: SSE(Server-Sent Events) 스트림 방식으로 응답이 올 수 있습니다.
      operationId: askAI
      parameters:
        - name: question
          in: query
          description: 질문 내용
          required: true
          schema:
            type: string
            example: 전과 기간
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/ai/AIResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 응답되었습니다.
                    data:
                      answer: 전과 신청 기간은 공지사항을 기준으로 합니다.
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  # ------------------------------------------------------------------
  # [학사일정] Academic
  # ------------------------------------------------------------------
  /api/v2/academic-events:
    get:
      tags:
        - Academic
      summary: 학사일정 조회
      description: 지정된 기간에 해당하는 학사일정 목록을 조회합니다.
      operationId: getAcademicEvents
      parameters:
        - name: startDate
          in: query
          description: 조회 시작일 (yyyy-MM-dd 형식)
          required: false
          schema:
            type: string
            format: date
            example: '2024-02-01'
        - name: endDate
          in: query
          description: 조회 종료일 (yyyy-MM-dd 형식)
          required: false
          schema:
            type: string
            format: date
            example: '2024-03-01'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ./components/schemas/academic/AcademicEventResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 조회되었습니다.
                    data:
                      - subject: 1학기 수강신청
                        startDate: '2024-02-14'
                        endDate: '2024-02-16'
                    # ------------------------------------------------------------------
                    # [신고] Report
                    # ------------------------------------------------------------------
  /api/v2/reports:
    post:
      tags:
        - Report
      summary: 게시글/댓글 신고
      description: 부적절한 게시글이나 댓글을 신고합니다.
      operationId: createReport
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./components/schemas/report/ReportRequest.yaml
            examples:
              Success:
                value:
                  boardId: '1'
                  commentId: '1'
                  category: 욕설
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./components/schemas/common/BaseResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 신고가 접수되었습니다.
                    data: null
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
  # ------------------------------------------------------------------
  # [동아리] Club
  # ------------------------------------------------------------------
  /api/v2/clubs/divisions:
    get:
      tags:
        - Club
      summary: 동아리 소속(division) 목록 조회
      description: |
        동아리 소속 목록이 가변적으로 변할 수 있으므로, 클라이언트에 현재 지원하는 소속 목록을 API로 전달합니다.
        필터 UI(드롭다운 등) 구성 시 이 목록을 사용하세요.

        **값 형식:**
        - 서버 내부 데이터는 UPPERCASE로 저장/관리됩니다 (예: CENTRAL, ENGINEERING)
        - 클라이언트와의 API 통신 시에는 lowercase로 변환하여 사용합니다 (예: central, engineering)
        - API 응답의 code 값은 lowercase로 내려갑니다. (예: central, engineering)

        가능한 소속 값 (UPPERCASE 기준):
        - 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
      operationId: getClubDivisions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/club/ClubDivisionListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 지원하는 동아리 소속 조회에 성공하였습니다
                    data:
                      divisions:
                        - code: central
                          koreanName: 중앙
                        - code: engineering
                          koreanName: 공과대학
                        - code: liberal_arts
                          koreanName: 문과대학
  /api/v2/clubs:
    get:
      tags:
        - Club
      summary: 동아리 목록 조회
      description: |
        필터 조건에 맞는 동아리 목록을 조회합니다. data 안에 clubs(배열)을 반환합니다.

        필터:
        - category: 동아리 카테고리로 필터 (1개만 선택 가능). 생략 시 카테고리 무관
        - division: 동아리 소속으로 필터. 여러 개 선택 시 콤마(,)로 구분하여 전달 (예: division=central,engineering). 생략 시 소속 무관.
          **값 형식:** 서버 내부는 UPPERCASE로 저장되지만, API 요청/응답에서는 lowercase로 전달됩니다. 요청 시 lowercase 값을 보내고, 응답의 division 필드도 lowercase로 반환됩니다.
      operationId: getClubs
      security:
        - BearerAuth: []
        - {}
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderOptional'
        - name: category
          in: query
          description: 동아리 카테고리로 필터 (ClubCategory enum 값 1개)
          schema:
            $ref: ./components/schemas/club/ClubCategory.yaml
            type: string
        - name: division
          in: query
          description: |
            동아리 소속으로 필터. 여러 개 선택 시 콤마(,)로 구분하여 전달합니다. 생략 시 소속 무관.

            **값 형식:** 서버 내부는 UPPERCASE로 저장되지만, API 요청/응답에서는 lowercase로 전달됩니다.
            - 요청 시: lowercase 값 사용 (예: division=central,engineering)
            - 응답 시: division 필드에 lowercase 값 반환 (예: "central", "engineering")
          required: false
          schema:
            type: string
          example: 'central,engineering'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/club/ClubListResponse.yaml
              examples:
                Success:
                  summary: '첫 페이지, 다음 페이지 있음'
                  value:
                    code: 200
                    message: 동아리 목록 조회에 성공하였습니다
                    data:
                      clubs:
                        - id: 1
                          name: Kuring
                          summary: 건국대학교 공지사항 알림 서비스 개발 동아리
                          iconImageUrl: 'https://api.kuring.com/images/club_icon.png'
                          category: academic
                          division: central
                          isSubscribed: false
                          subscriberCount: 19
                          recruitStartDate: '2026-05-01T00:00:00'
                          recruitEndDate: '2026-06-03T23:59:59'
                        - id: 2
                          name: 리드미
                          summary: 책 속에 빠져 인사이트를 나누는 독서 모임
                          iconImageUrl: 'https://api.kuring.com/images/club_icon_2.png'
                          category: academic
                          division: central
                          isSubscribed: true
                          subscriberCount: 128
                          recruitStartDate: '2026-04-15T00:00:00'
                          recruitEndDate: '2026-05-31T23:59:59'
                EmptyResult:
                  summary: 조건에 맞는 동아리 없음
                  value:
                    code: 200
                    message: 동아리 목록 조회에 성공하였습니다
                    data:
                      clubs: []
                FilteredByCategory:
                  summary: 카테고리로 필터 (예 category=ACADEMIC)
                  value:
                    code: 200
                    message: 동아리 목록 조회에 성공하였습니다
                    data:
                      clubs:
                        - id: 3
                          name: 알고리즘 스터디
                          summary: 알고리즘 문제 풀이 및 스터디
                          iconImageUrl: 'https://api.kuring.com/images/club_algo.png'
                          category: academic
                          division: computer_science
                          isSubscribed: false
                          subscriberCount: 32
                          recruitStartDate: '2026-05-10T00:00:00'
                          recruitEndDate: '2026-06-01T23:59:59'
                FilteredByDivision:
                  summary: '소속 복수 선택 (예 division=central,engineering)'
                  value:
                    code: 200
                    message: 동아리 목록 조회에 성공하였습니다
                    data:
                      clubs:
                        - id: 1
                          name: Kuring
                          summary: 건국대학교 공지사항 알림 서비스 개발 동아리
                          iconImageUrl: 'https://api.kuring.com/images/club_icon.png'
                          category: academic
                          division: central
                          isSubscribed: false
                          subscriberCount: 19
                          recruitStartDate: '2026-05-01T00:00:00'
                          recruitEndDate: '2026-06-03T23:59:59'
                        - id: 4
                          name: 로봇연구회
                          summary: 공과대 로봇 연구 동아리
                          iconImageUrl: 'https://api.kuring.com/images/club_robot.png'
                          category: academic
                          division: engineering
                          isSubscribed: true
                          subscriberCount: 28
                          recruitStartDate: '2026-05-15T00:00:00'
                          recruitEndDate: '2026-06-10T23:59:59'
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  '/api/v2/clubs/{id}':
    get:
      tags:
        - Club
      summary: 동아리 상세 조회
      description: |
        동아리 상세 정보를 조회합니다.
      operationId: getClubDetail
      security:
        - BearerAuth: []
        - {}
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderOptional'
        - name: id
          in: path
          required: true
          description: 동아리 ID
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/club/ClubDetailResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 동아리 상세 조회에 성공하였습니다
                    data:
                      id: 1
                      name: 리드미
                      summary: '단순히 책만 읽는 독서모임이 아닌, 책 속에 빠져 인사이트를 나누는 모임'
                      category: academic
                      division: central
                      subscriberCount: 128
                      isSubscribed: true
                      instagramUrl: 'https://instagram.com/kuring.official'
                      youtubeUrl: null
                      etcUrl: null
                      description: 저희 리드미는 2020년부터 시작된...
                      qualifications: |-
                        건국대학교 재학생 및 휴학생 누구나
                        (매주 목요일 활동 가능하신 분)
                      recruitmentStatus: recruiting
                      recruitStartAt: '2026-03-02T00:00:00'
                      recruitEndAt: '2026-03-15T23:59:59'
                      applyUrl: 'https://forms.gle/xyz...'
                      posterImageUrl: 'https://api.kuring.com/images/club_poster_readme.png'
                      location:
                        building: sanghuh_library
                        room: '101'
                        lon: 127.074
                        lat: 37.541
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
  /api/v2/users/subscriptions/clubs:
    get:
      tags:
        - Club
      summary: 구독한 동아리 목록 조회
      description: 사용자가 구독한 동아리 목록을 조회합니다. data 안에 clubs(배열)을 반환합니다.
      operationId: getUserSubscribedClubs
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      data:
                        $ref: ./components/schemas/club/ClubListResponse.yaml
              examples:
                Success:
                  value:
                    code: 200
                    message: 구독한 동아리 목록 조회에 성공하였습니다
                    data:
                      clubs:
                        - id: 1
                          name: Kuring
                          summary: 건국대학교 공지사항 알림 서비스 개발 동아리
                          iconImageUrl: 'https://api.kuring.com/images/club_icon.png'
                          category: academic
                          division: central
                          isSubscribed: true
                          subscriberCount: 19
                          recruitStartDate: '2026-05-01T00:00:00'
                          recruitEndDate: '2026-06-03T23:59:59'
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
    post:
      tags:
        - Club
      summary: 사용자 동아리 구독 등록
      operationId: addClubSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                  description: 구독할 동아리 ID (clubId)
                  example: 1
                  x-stoplight:
                    id: 6gj18cdzbuxr1
      responses:
        '200':
          description: 구독 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      message:
                        type: string
                        example: 구독에 성공했습니다.
                      data:
                        type: object
                        required:
                          - subscriptionCount
                        properties:
                          subscriptionCount:
                            type: integer
                            description: 사용자의 동아리 구독 개수
                            example: 5
              examples:
                Success:
                  value:
                    code: 200
                    message: 구독에 성공했습니다.
                    data:
                      subscriptionCount: 5
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
      x-stoplight:
        id: avx1ex1702exu
      description: 로그인한 사용자가 동아리 구독을 등록합니다.
  '/api/v2/users/subscriptions/clubs/{clubId}':
    delete:
      tags:
        - Club
      summary: 사용자 동아리 구독 삭제
      operationId: deleteClubSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserTokenHeaderRequired'
        - name: clubId
          in: path
          required: true
          description: 구독 해제할 동아리 ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: 취소 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./components/schemas/common/BaseResponse.yaml
                  - type: object
                    properties:
                      message:
                        type: string
                        example: 구독이 취소되었습니다.
                      data:
                        type: object
                        required:
                          - subscriptionCount
                        properties:
                          subscriptionCount:
                            type: integer
                            description: 사용자의 동아리 구독 개수
                            example: 4
              examples:
                Success:
                  value:
                    code: 200
                    message: 구독이 취소되었습니다.
                    data:
                      subscriptionCount: 4
        '400':
          $ref: '#/components/responses/BadRequestUserToken'
        '401':
          $ref: '#/components/responses/UnauthorizedJwt'
      x-stoplight:
        id: 6qd89rl96a1he
      description: 사용자가 동아리 구독을 해제합니다. path의 clubId로 대상 동아리를 지정합니다.