openapi: 3.0.4
info:
  title: Quiz Maker API
  description: API documentation for Quiz App
  version: 1.0.0

servers:
  - url: http://127.0.0.1:5000/api
    description: Local Server
  - url: http://api.example.com/api
    description: Production Server

tags:
  - name: Auth
    description: Authentication endpoints
  - name: User
    description: User data endpoints
  - name: Quiz
    description: Quiz endpoints
  - name: History
    description: Quiz history endpoints
  - name: Subject
    description: Subject management endpoints
  - name: Session
    description: Session management endpoints

paths:
  /login:
    post:
      summary: Login
      tags: [Auth]
      requestBody:
        $ref: "#/components/requestBodies/LoginRequest"
      responses:
        "200":
          $ref: "#/components/responses/AuthTokenResponse"
        "400":
          $ref: "#/components/responses/BadRequestLogin"

  /login/google:
    post:
      summary: Login with Google
      tags: [Auth]
      requestBody:
        $ref: "#/components/requestBodies/GoogleLoginRequest"
      responses:
        "200":
          $ref: "#/components/responses/AuthTokenResponse"
        "400":
          $ref: "#/components/responses/BadRequestGoogleLogin"

  /logout:
    post:
      summary: Logout
      tags: [Auth]
      responses:
        "200":
          $ref: "#/components/responses/LogoutSuccess"

  /register:
    post:
      summary: Register
      tags: [User]
      requestBody:
        $ref: "#/components/requestBodies/RegisterRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserCreated"
        "409":
          $ref: "#/components/responses/UserExists"

  /user:
    get:
      summary: Get User
      tags: [User]
      responses:
        "200":
          $ref: "#/components/responses/UserData"

  /user/update:
    post:
      summary: Update user profile
      tags: [User]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier of the user
                  example: "123abc"
                name:
                  type: string
                  nullable: true
                  example: "John Doe"
                birth_date:
                  type: string
                  format: date
                  nullable: true
                  example: "1990-01-01"
                locale:
                  type: string
                  nullable: true
                  example: "en-US"
                phone:
                  type: string
                  nullable: true
                  example: "+628123456789"
              required:
                - id
      responses:
        "200":
          description: Profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User profile updated successfully.
                  data:
                    type: object
                    nullable: true
                    example: null
                  meta:
                    type: object
                    nullable: true
                    example: null

  /quiz:
    post:
      summary: Create a new quiz
      tags: [Quiz]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuizCreateRequest"
      responses:
        "201":
          description: Quiz created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Quiz created successfully
                  quiz_id:
                    type: string
                    example: "60f6c2d2e1f1c4567a123abc"
        "400":
          $ref: "#/components/responses/BadRequest"

  /quiz/{id}:
    get:
      summary: Get quiz by ID
      tags: [Quiz]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 68283dc9806020760d14e963
      responses:
        "200":
          description: Quiz found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Quiz Found
                  data:
                    $ref: "#/components/schemas/QuizDetails"
                  meta:
                    type: object
        "404":
          $ref: "#/components/responses/NotFound"

  /quiz/user/{user_id}:
    get:
      summary: Get quizzes by user ID
      description: Returns a list of quizzes created by a specific user
      tags: [Quiz]
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            example: 680f0e63180b5c19b3751d42
        - name: page
          in: query
          required: false
          schema:
            type: integer
            example: 1
      responses:
        "200":
          description: List of quizzes
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Quiz list retrieved successfully
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/QuizDetails"
                  meta:
                    $ref: "#/components/schemas/PaginationMeta"
        "404":
          $ref: "#/components/responses/NotFound"

  /quiz/recomendation:
    get:
      summary: Get recommended quizzes
      description: Returns a list of recommended quizzes for the user
      tags: [Quiz]
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Successfully retrieved recommendation quiz list
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: success retrieve recommendation quiz
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/RecommendedQuiz"

  /quiz/search:
    get:
      summary: Search quizzes by keyword
      description: Returns a list of quizzes matching the search keyword
      tags: [Quiz]
      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
            example: Sejarah
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Search result
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/RecommendedQuiz"
                  meta:
                    $ref: "#/components/schemas/SearchMeta"

  /quiz/ai:
    post:
      summary: Generate labeling quiz from passage
      description: Generate quiz-style labeled data from a given historical passage
      tags: [Quiz]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sentence:
                  type: string
                  example: >
                    Ratu Sima adalah penguasa di Kerajaan Kalingga. Ia digambarkan sebagai seorang pemimpin wanita yang tegas dan taat terhadap peraturan...
      responses:
        "200":
          description: Successfully labeled the quiz data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: succes labeling
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LabeledQuestion"
        "400":
          $ref: "#/components/responses/BadRequest"

  /quiz/answer:
    post:
      summary: Submit quiz answers
      description: Submit answers for a specific quiz session
      tags: [Quiz]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuizAnswerSubmission"
      responses:
        "200":
          description: Answers submitted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /quiz/answer/session:
    post:
      summary: Get submitted quiz answers by session
      description: Retrieve user's quiz answers using session ID and user ID
      tags: [Quiz]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  type: string
                  example: 682a26b3bedac6c20a215452
                user_id:
                  type: string
                  example: 680f0e63180b5c19b3751d42
      responses:
        "200":
          description: Successfully retrieved the answer
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully retrieved the answer
                  data:
                    $ref: "#/components/schemas/UserAnswerSession"
        "404":
          $ref: "#/components/responses/NotFound"

  /history/{user_id}:
    get:
      summary: Get quiz answer history by user
      description: Retrieve a list of all quiz history for a given user
      tags: [History]
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            example: 680f0e63180b5c19b3751d42
      responses:
        "200":
          description: Successfully retrieved history data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: retrive history data
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AnswerHistoryItem"
        "404":
          $ref: "#/components/responses/NotFound"

  /history/detail/{answer_id}:
    get:
      summary: Get detail quiz history
      description: Retrieve detailed quiz answer history for a specific answer ID
      tags: [History]
      parameters:
        - name: answer_id
          in: path
          required: true
          schema:
            type: string
            example: 6828bcddb5418bf21ab424b2
      responses:
        "200":
          description: success retrive detail history data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: success retrive detail history data
                  data:
                    $ref: "#/components/schemas/AnswerDetailData"

  /subject:
    get:
      summary: Get all subjects
      description: Retrieve a list of all available subjects
      tags: [Subject]
      responses:
        "200":
          description: success retrieve subject
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: success retrieve subject
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Subject"

    post:
      summary: Create a new subject
      tags: [Subject]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Teknik Kimia
                alias:
                  type: string
                  example: KIM
                description:
                  type: string
                  example: basic Kimia
              required:
                - name
                - alias
                - description
      responses:
        "200":
          description: Subject successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Subject created
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 683178ffac911e8a9d04bb0e
                  meta:
                    type: object
                    nullable: true
                    example: null

  /session:
    post:
      summary: Create a new quiz session
      tags: [Session]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quiz_id:
                  type: string
                  example: 6815da9f37a1ce472ba72819
                host_id:
                  type: string
                  example: 680f0e63180b5c19b3751d42
                limit_participan:
                  type: integer
                  example: 2
              required:
                - quiz_id
                - host_id
                - limit_participan
      responses:
        "200":
          description: Successfully created a session
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: succes create room
                  data:
                    type: object
                    properties:
                      session_id:
                        type: string
                        example: 68317a6a48d97464ec3aaf1c
                      session_code:
                        type: string
                        example: AE5AFE
                  meta:
                    type: object
                    nullable: true
                    example: null

components:
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        example: 1

    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        example: 4

  requestBodies:
    LoginRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Login"

    GoogleLoginRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GoogleLogin"

    RegisterRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Register"

    UpdateUserRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateUser"

  responses:
    AuthTokenResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              token:
                type: string
                example: <jwt_token>

    BadRequestLogin:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Invalid email or password

    BadRequestGoogleLogin:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Invalid token

    LogoutSuccess:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessMessage"
          example:
            message: Logout successfully

    UserCreated:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessMessage"
          example:
            message: User created successfully

    UserExists:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Email already registered

    UserData:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"

    UserUpdated:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessMessage"
          example:
            message: User updated successfully

    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Resource not found

  schemas:
    Login:
      type: object
      properties:
        email:
          type: string
          example: user@example.com
        password:
          type: string
          example: rahasia

    GoogleLogin:
      type: object
      properties:
        token_id:
          type: string
          example: <google_token>

    Register:
      type: object
      properties:
        email:
          type: string
          example: user@example.com
        password:
          type: string
          example: secure_password
        name:
          type: string
          example: John Doe
        birth_date:
          type: string
          example: 1990-01-01

    UpdateUser:
      type: object
      properties:
        email:
          type: string
          example: newemail@example.com

    User:
      type: object
      properties:
        id:
          type: string
          example: 680f0e63180b5c19b3751d42
        name:
          type: string
          example: John Doe
        email:
          type: string
          example: user@example.com

    SuccessMessage:
      type: object
      properties:
        message:
          type: string

    SuccessResponse:
      type: object
      properties:
        message:
          type: string
          example: Operation completed successfully

    ErrorMessage:
      type: object
      properties:
        message:
          type: string
          example: An error occurred

    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 25
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 10

    QuizCreateRequest:
      type: object
      properties:
        title:
          type: string
          example: Sejarah Indonesia
        description:
          type: string
          example: Kuis tentang sejarah Indonesia
        is_public:
          type: boolean
          example: true
        author_id:
          type: string
          example: 680f0e63180b5c19b3751d42
        subject_id:
          type: string
          example: 68131eac43a09ed7dbb2cf44
        questions:
          type: array
          items:
            $ref: "#/components/schemas/QuizQuestion"

    QuizQuestion:
      type: object
      properties:
        index:
          type: integer
          example: 1
        question:
          type: string
          example: Siapakah ketua Wali Songo yang juga dikenal sebagai Sunan Gresik?
        target_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
          example: Maulana Malik Ibrahim
        duration:
          type: integer
          example: 30
        type:
          type: string
          enum: [fill_the_blank, true_false, option]
          example: fill_the_blank
        options:
          type: array
          items:
            type: string
          nullable: true
          example: null

    QuizDetails:
      type: object
      properties:
        id:
          type: string
          example: 68283dc9806020760d14e963
        author_id:
          type: string
          example: 680f0e63180b5c19b3751d42
        subject_id:
          type: string
          example: 68131eac43a09ed7dbb2cf44
        subject_alias:
          type: string
          example: IPA
        title:
          type: string
          example: Sejarah Indonesia - Proklamasi dan Kemerdekaan
        description:
          type: string
          example: Kuis ini membahas peristiwa penting seputar proklamasi dan kemerdekaan Indonesia serta tokoh-tokoh terkait.
        is_public:
          type: boolean
          example: true
        date:
          type: string
          example: 17-May-2025
        time:
          type: string
          example: 14:30
        total_quiz:
          type: integer
          example: 10
        limit_duration:
          type: integer
          example: 300
        question_listings:
          type: array
          items:
            $ref: "#/components/schemas/QuizQuestion"

    RecommendedQuiz:
      type: object
      properties:
        quiz_id:
          type: string
          example: 68283dc9806020760d14e963
        author_id:
          type: string
          example: 680e5a6d2f480bd75db17a09
        author_name:
          type: string
          example: robbani
        title:
          type: string
          example: Sejarah Indonesia - Proklamasi dan Kemerdekaan
        description:
          type: string
          example: Kuis ini membahas peristiwa penting seputar proklamasi dan kemerdekaan Indonesia serta tokoh-tokoh terkait.
        date:
          type: string
          example: 17-May-2025
        total_quiz:
          type: integer
          example: 10
        duration:
          type: integer
          example: 300

    SearchMeta:
      type: object
      properties:
        total_page:
          type: integer
          example: 3
        current_page:
          type: integer
          example: 2
        total_data:
          type: integer
          example: 4
        total_all_data:
          type: integer
          example: 9

    LabeledQuestion:
      type: object
      properties:
        qustion:
          type: string
          example: kerajaan kalingga disebutkan di di sungai
        answer:
          type: string
          example: true

    AnswerHistoryItem:
      type: object
      properties:
        quiz_id:
          type: string
          example: 68283dc9806020760d14e963
        answer_id:
          type: string
          example: 6828bcddb5418bf21ab424b2
        title:
          type: string
          example: Sejarah Indonesia - Proklamasi dan Kemerdekaan
        description:
          type: string
          example: Kuis ini membahas peristiwa penting seputar proklamasi dan kemerdekaan Indonesia serta tokoh-tokoh terkait.
        total_correct:
          type: integer
          example: 8
        total_question:
          type: integer
          example: 10
        date:
          type: string
          example: 2025-05-18 19:02:02

    QuizAnswerSubmission:
      type: object
      properties:
        session_id:
          type: string
          example: abc123-session-id
        quiz_id:
          type: string
          example: 6815da9f37a1ce472ba72819
        user_id:
          type: string
          example: 68163d981f2241b7d8210c21
        answered_at:
          type: string
          format: date-time
          example: 2025-04-25T10:15:00Z
        answers:
          type: array
          items:
            $ref: "#/components/schemas/QuizAnswerItem"

    QuizAnswerItem:
      type: object
      properties:
        question_index:
          type: integer
          example: 1
        answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
          example: Maulana Malik Ibrahim
        is_correct:
          type: boolean
          example: true
        time_spent:
          type: number
          format: float
          example: 6.5

    UserAnswerSession:
      type: object
      properties:
        id:
          type: string
          example: 682a26e6bedac6c20a215453
        session_id:
          type: string
          example: 682a26b3bedac6c20a215452
        quiz_id:
          type: string
          example: 682a120f18339f4cc31318e4
        user_id:
          type: string
          example: 680f0e63180b5c19b3751d42
        answered_at:
          type: string
          example: 2025-05-19 01:28:22
        answers:
          type: array
          items:
            $ref: "#/components/schemas/AnswerDetail"
        total_score:
          type: integer
          example: 100
        total_correct:
          type: integer
          example: 1

    AnswerDetail:
      type: object
      properties:
        index:
          type: integer
          example: 1
        question:
          type: string
          example: Siapakah ketua Wali Songo yang juga dikenal sebagai Sunan Gresik?
        target_answer:
          type: string
          example: Maulana Malik Ibrahim
        duration:
          type: integer
          example: 30
        type:
          type: string
          enum: [fill_the_blank, true_false, option]
          example: fill_the_blank
        options:
          type: array
          items:
            type: string
          nullable: true
          example: null
        answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
          example: Maulana Malik Ibrahim
        is_correct:
          type: boolean
          example: true
        time_spent:
          type: number
          format: float
          example: 8.0

    AnswerDetailData:
      type: object
      properties:
        answer_id:
          type: string
          example: 6828bcddb5418bf21ab424b2
        quiz_id:
          type: string
          example: 68283dc9806020760d14e963
        title:
          type: string
          example: Sejarah Indonesia - Proklamasi dan Kemerdekaan
        description:
          type: string
          example: Kuis ini membahas peristiwa penting seputar proklamasi dan kemerdekaan Indonesia serta tokoh-tokoh terkait.
        author_id:
          type: string
          example: 680f0e63180b5c19b3751d42
        answered_at:
          type: string
          example: 17-May-2025
        total_correct:
          type: integer
          example: 8
        total_score:
          type: integer
          example: 80
        total_solve_time:
          type: number
          example: 240.5
        question_listings:
          type: array
          items:
            $ref: "#/components/schemas/AnsweredQuestion"

    AnsweredQuestion:
      type: object
      properties:
        index:
          type: integer
          example: 1
        question:
          type: string
          example: Siapakah ketua Wali Songo yang juga dikenal sebagai Sunan Gresik?
        type:
          type: string
          enum: [fill_the_blank, true_false, option]
          example: fill_the_blank
        target_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
          example: Maulana Malik Ibrahim
        user_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
          example: Maulana Malik Ibrahim
        is_correct:
          type: boolean
          example: true
        time_spent:
          type: number
          example: 25.3
        options:
          type: array
          items:
            type: string
          nullable: true
          example: null

    Subject:
      type: object
      properties:
        id:
          type: string
          example: 68131eac43a09ed7dbb2cf44
        name:
          type: string
          example: Ilmu Pengetahuan Alam
        alias:
          type: string
          example: IPA
        description:
          type: string
          example: Pelajaran tentang sains dan alam