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:
        "200":
          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"

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: "대표 언어 (필수)"
      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
      required: [uid, notificationPreference, cron]

    # -----------------------------------------------------------
    # 유저 정보중 업데이트 가능한 것들을 모두 널러블로 열어둡니다.
    # -----------------------------------------------------------
    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]

    # -----------------------------------------------------------
    # 유저 노티피케이션을 생성합니다.
    # -----------------------------------------------------------
    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]

    # -----------------------------------------------------------
    # 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"

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

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