api.yml

openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /auth/google:
    post:
      tags:
        - auth
      summary: "Google 로그인을 요청합니다."
      operationId: "googleLogin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoogleLoginRequest"
      responses:
        "201":
          description: JWT 토큰 발급 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenDto"

  /auth/apple:
    post:
      tags:
        - auth
      summary: "apple 로그인을 요청합니다."
      operationId: "appleLogin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppleLoginRequest"
      responses:
        "201":
          description: JWT 토큰 발급 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenDto"

  /auth/refresh:
    post:
      tags:
        - auth
      summary: "서버에서 발급한 refresh token을 통해 accessToken을 다시 받아옵니다."
      operationId: "authRefresh"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refreshToken:
                  type: string
                  description: "리프레시 토큰"
              required:
                - refreshToken
      responses:
        "200":
          description: JWT 토큰 발급 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenDto"

  /user:
    post:
      tags:
        - user
      summary: "새로운 유저를 생성합니다."
      operationId: "createUser"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: "유저 생성 성공"

  /user/me:
    get:
      tags:
        - user
      summary: "jwt 기반으로 유저의 정보를 가져옵니다."
      operationId: "getUserMe"
      responses:
        "200":
          description: "유저 정보 반환 성공"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
    patch:
      tags:
        - user
      summary: 유저의 정보를 변경합니다. 아직은 큰 차이 없으니 온보딩에서 사용한 schema를 재사용합니다.
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "201":
          description: "유저 update 성공"

  /user/me/social:
    get:
      tags:
        - user
      summary: 유저의 소셜 로그인 정보를 가져옵니다.
      description: 딱히 다른 곳에서 사용하지 않을 정보이기 때문에 그냥 email만 반환하는 식으로 구현합니다.
      operationId: getUserMeSocial
      responses:
        "200":
          description: 유저 소셜 로그인 정보 반환 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSocialResponse"

  /user/me/notification/{notification}:
    get:
      tags:
        - user
      summary: 유저의 notification 중 특정 enum값을 가져옵니다
      operationId: getUserMeNotification
      parameters:
        - name: notification
          in: path
          required: true
          description: 가져올 알림 유형
          schema:
            $ref: "#/components/schemas/NotificationEnum"
      responses:
        "200":
          description: 푸시에 대한 유저의 설정 정보를 가져옵니다.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseUserNotification"
        "404":
          description: 해당 notification 설정을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    patch:
      tags:
        - user
      summary: 유저의 특정 알림(notification) 활성화 여부를 변경합니다. 이때 프론트에서 넘겨주는 값으로 변경합니다.
      operationId: updateUserNotification
      parameters:
        - name: notification
          in: path
          required: true
          description: 변경할 알림 유형
          schema:
            $ref: "#/components/schemas/NotificationEnum"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive:
                  type: boolean
                cron:
                  type: string
      responses:
        "202":
          description: 변경에 성공하고 변경된 값을 프론트에 내려줍니다.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseUserNotification"
        "404":
          description: 해당 알림을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /user/me/delete:
    post:
      tags:
        - user
      summary: 회원탈퇴를 진행합니다.
      operationId: userMeDelete
      responses:
        "201":
          description: 회원 탈퇴에 성공합니다.

components:
  schemas:
    # -----------------------------------------------------------
    # 공통 Timestamp(읽기 전용) : createdAt, updatedAt, deletedAt
    # -----------------------------------------------------------
    Timestamped:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: "생성 일시 (DB 자동)"
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: "수정 일시 (DB 자동)"
          readOnly: true
        deletedAt:
          type: string
          format: date-time
          description: "삭제 일시 (소프트 딜리트)"
          readOnly: true

    # -----------------------------------------------------------
    # Enum 정의
    # -----------------------------------------------------------
    LanguageEnum:
      type: string
      enum: [JA, ZH, FR, ES, DE, EN, KO]
      description: "일본어, 중국어, 프랑스어, 스페인어, 독일어, 영어, 한국어"

    GenderEnum:
      type: string
      enum: [MALE, FEMALE, OTHER]
      description: "유저 성별 (MALE/FEMALE/OTHER)"

    LevelEnum:
      type: string
      enum: [A, B, C, D, E]
      description: "학습 수준 (A/B/C/D/E)"

    NotificationEnum:
      type: string
      enum: [DAILY_STUDY]
      description: "push 알림 타입입니다."

    NotificationStatusEnum:
      type: string
      enum: [SUCCESS, FAIL, SCHEDULE, CANCEL]
      description: "push 상태를 관리하는 enum입니다."

    PointEnum:
      type: string
      enum: [DAILY_STUDY]
      description: "유저가 포인트에 대한 조건을 구분하는 enum입니다."

    VoiceTypeEnum:
      type: string
      enum: [A, B, C]
      description: "ai 목소리에 맵핑되는 enum입니다."

    # -----------------------------------------------------------
    # BaseUser : UserEntity가 가진 주요 필드
    # (nickname, language 등을 포함)
    # -----------------------------------------------------------
    BaseUser:
      type: object
      properties:
        uid:
          type: string
          format: uuid
        nickname:
          type: string
          description: "유저 닉네임 (필수)"
        language:
          $ref: "#/components/schemas/LanguageEnum"
          description: "대표 언어 (필수)"
        profileImage:
          type: string
      required: [uid, nickname, language]

    # -----------------------------------------------------------
    # BaseUserInfo : UserInfoEntity가 가진 필드들
    # (모두 optional로 가정)
    # -----------------------------------------------------------
    BaseUserInfo:
      type: object
      properties:
        uid:
          type: string
          format: uuid
        gender:
          $ref: "#/components/schemas/GenderEnum"
          description: "옵션 - 성별"
          nullable: true
        yearOfBirth:
          type: integer
          format: int32
          description: "옵션 - 태어난 해"
          nullable: true
        occupation:
          type: string
          description: "옵션 - 직업"
          nullable: true
        interest:
          type: array
          items:
            type: string
          description: "옵션 - 관심사"
          nullable: true
        purpose:
          type: string
          description: "옵션 - 학습 목적"
          nullable: true
        languageSecond:
          $ref: "#/components/schemas/LanguageEnum"
          description: "옵션 - 2차 언어 (ex. JP)"
          nullable: true
        studyPlace:
          type: string
          description: "옵션 - 학습 장소 (ex. ONLINE, OFFLINE)"
          nullable: true
        mbti:
          type: string
          description: "옵션 - MBTI"
          nullable: true
      required: [uid]

    # -----------------------------------------------------------
    # BaseUserStudyInfo : UserStudyInfoEntity가 가진 필드들
    # -----------------------------------------------------------
    BaseUserStudyInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        uid:
          type: string
          format: uuid
        level:
          $ref: "#/components/schemas/LevelEnum"
          description: "학습 난이도"
        voiceType:
          $ref: "#/components/schemas/VoiceTypeEnum"
          description: "ai 목소리 타입"
        language:
          $ref: "#/components/schemas/LanguageEnum"
          description: "지금 내가 학습하는 언어"
        streakDays:
          type: integer
          format: int32
          description: "연속 학습 일 수"
        sentenceAmount:
          type: integer
          format: int32
          description: "학습할 문장 수"
      required:
        [id, uid, level, voiceType, language, streakDays, sentenceAmount]

    # -----------------------------------------------------------
    # BaseUserPoint : UserStudyPointEntity가 가진 필드들
    # -----------------------------------------------------------
    BaseUserPoint:
      type: object
      properties:
        uid:
          type: string
          format: uuid
        amount:
          type: integer
          description: "유저 포인트"
      required: [uid, amount]

    # -----------------------------------------------------------
    # BaseUserNotification : UserNotificationEntity가 가진 필드들
    # -----------------------------------------------------------
    BaseUserNotification:
      type: object
      properties:
        uid:
          type: string
          format: uuid
        notificationPreference:
          $ref: "#/components/schemas/NotificationEnum"
        cron:
          type: string
        isActive:
          type: boolean
      required: [uid, notificationPreference, cron, isActive]

    # -----------------------------------------------------------
    # 유저 정보중 업데이트 가능한 것들을 모두 널러블로 열어둡니다.
    # -----------------------------------------------------------
    UpdateUser:
      type: object
      properties:
        nickname:
          type: string
          description: "유저 닉네임 (필수)"
        language:
          $ref: "#/components/schemas/LanguageEnum"
          description: "대표 언어 (필수)"

    # -----------------------------------------------------------
    # 유저 정보중 업데이트 가능한 것들을 모두 널러블로 열어둡니다.
    # -----------------------------------------------------------
    UpdateUserInfo:
      type: object
      properties:
        gender:
          $ref: "#/components/schemas/GenderEnum"
          description: "옵션 - 성별"
        yearOfBirth:
          type: integer
          format: int32
          description: "옵션 - 태어난 해"
        occupation:
          type: string
          description: "옵션 - 직업"
        interest:
          type: array
          items:
            type: string
          description: "옵션 - 관심사"
        purpose:
          type: string
          description: "옵션 - 학습 목적"
        languageSecond:
          $ref: "#/components/schemas/LanguageEnum"
          description: "옵션 - 2차 언어 (ex. JP)"
        studyPlace:
          type: string
          description: "옵션 - 학습 장소 (ex. ONLINE, OFFLINE)"
        mbti:
          type: string
          description: "옵션 - MBTI"

    # -----------------------------------------------------------
    # 유저 학습정보 중 업데이트 가능한 것들을 열어둡니다.
    # -----------------------------------------------------------
    CreateUserStudyInfo:
      type: object
      properties:
        level:
          $ref: "#/components/schemas/LevelEnum"
          description: "학습 난이도"
        language:
          $ref: "#/components/schemas/LanguageEnum"
          description: "학습할 언어"
      required: [level, language]

    UpdateUserStudyInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        level:
          $ref: "#/components/schemas/LevelEnum"
          description: "학습 난이도"
        voiceType:
          $ref: "#/components/schemas/VoiceTypeEnum"
          description: "ai 목소리 타입"
        sentenceAmount:
          type: integer
          format: int32
          description: "학습할 문장 수"
      required: [id]

    # -----------------------------------------------------------
    # 유저 노티피케이션을 생성합니다.
    # -----------------------------------------------------------
    CreateUserNotification:
      type: object
      properties:
        notificationPreference:
          $ref: "#/components/schemas/NotificationEnum"
        cron:
          type: string
      required: [notificationPreference, cron]

    # -----------------------------------------------------------
    # CreateUserRequest : User 생성 요청
    #  => BaseUser + BaseUserInfo 를 상속(allOf)해서 합치기
    # -----------------------------------------------------------
    CreateUserRequest:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/UpdateUser"
        userInfo:
          $ref: "#/components/schemas/UpdateUserInfo"
        userStudyInfo:
          $ref: "#/components/schemas/CreateUserStudyInfo"
        userNotification:
          $ref: "#/components/schemas/CreateUserNotification"
      required: [user, userInfo, userStudyInfo, userNotification]

    UpdateUserRequest:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/UpdateUser"
        userInfo:
          $ref: "#/components/schemas/UpdateUserInfo"
        userStudyInfo:
          $ref: "#/components/schemas/UpdateUserStudyInfo"

    # -----------------------------------------------------------
    # UserResponse : User 조회 응답
    #  => Timestamped + BaseUser + BaseUserInfo
    #  => uid 같은 PK를 추가할 수도 있음
    # -----------------------------------------------------------
    UserResponse:
      allOf:
        - type: object
          properties:
            user:
              $ref: "#/components/schemas/BaseUser"
        - type: object
          properties:
            userInfo:
              $ref: "#/components/schemas/BaseUserInfo"
        - type: object
          properties:
            userStudyInfo:
              $ref: "#/components/schemas/BaseUserStudyInfo"
        - type: object
          properties:
            userPoint:
              $ref: "#/components/schemas/BaseUserPoint"

    UserSocialResponse:
      type: object
      properties:
        google:
          type: object
          properties:
            email:
              type: string
        apple:
          type: object
          properties:
            email:
              type: string

    # -----------------------------------------------------------
    # GoogleLoginRequest :
    #  => googleId, email, name(옵션) + (BaseUser) nickname/language 필수
    # -----------------------------------------------------------
    GoogleLoginRequest:
      type: object
      properties:
        language:
          type: string
          description: "디바이스의 언어를 가져옵니다."
        token:
          $ref: "#/components/schemas/TokenDto"
      required: [language, token]

    AppleLoginRequest:
      type: object
      properties:
        language:
          type: string
          description: "디바이스의 언어를 가져옵니다."
        appleId:
          type: string
          description: 애플 로그인의 정보 중 'user'값을 가져옵니다.
        email:
          type: string
          description: email값을 가져옵니다. (비공개 여부와 관계 없이 요청합니다.)
        familyName:
          type: string
          description: fullName 중 familyName을 의미합니다.
        givenName:
          type: string
          description: fullName 중 givenName을 의미합니다.
        middleName:
          type: string
          description: fullName 중 middleName을 의미합니다.
        namePrefix:
          type: string
          description: fullName 중 namePrefix을 의미합니다.
        nameSuffix:
          type: string
          description: fullName 중 nameSuffix을 의미합니다.
        nickname:
          type: string
          description: fullName 중 nickname을 의미합니다.
        nonce:
          type: string
        realUserStatus:
          type: integer
        state:
          type: string
      required: [language, appleId]

    # -----------------------------------------------------------
    # JWT 토큰 DTO
    # -----------------------------------------------------------
    TokenDto:
      type: object
      properties:
        accessToken:
          type: string
        refreshToken:
          type: string
      required: [accessToken]

    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP 상태 코드
        message:
          type: string
          description: 에러 메시지