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/v1
    description: Local Server
  - url: http://api.example.com/api/v1
    description: Production Server

tags:
  - name: Auth
    description: Authentication endpoints
  - name: User
    description: User data endpoints
  - name: Quiz
    description: Quiz endpoints
  # - name: Answer
  - name: History
  - name: Subject

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"

    put:
      summary: Update User
      tags: [User]
      requestBody:
        $ref: "#/components/requestBodies/UpdateUserRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserUpdated"

  /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":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"

  /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":
          description: Quiz not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"

  /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:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 25
                      page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
        "404":
          description: No quizzes found for user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"

  /quiz/recomendation:
    get:
      summary: Get recommended quizzes
      description: Returns a list of recommended quizzes for the user
      tags: [Quiz]
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            example: 4
      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
        - name: page
          in: query
          required: false
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            example: 4
      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":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"

  /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:
                type: object
                properties:
                  message:
                    type: string
                    example: Quiz answers submitted successfully
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"

  /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":
          description: Answer session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"

  /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":
          description: No history found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"

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

components:
  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

  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
        password:
          type: string
        name:
          type: string
        birth_date:
          type: string
    UpdateUser:
      type: object
      properties:
        email:
          type: string
          example: newemail@example.com
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
    SuccessMessage:
      type: object
      properties:
        message:
          type: string
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
    QuizCreateRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        is_public:
          type: boolean
        author_id:
          type: string
        subject_id:
          type: string
        questions:
          type: array
          items:
            $ref: "#/components/schemas/QuizQuestion"
    QuizQuestion:
      type: object
      properties:
        index:
          type: integer
        question:
          type: string
        target_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
        duration:
          type: integer
        type:
          type: string
          enum: [fill_the_blank, true_false, option]
        options:
          type: array
          items:
            type: string
          nullable: true
    QuizDetails:
      type: object
      properties:
        id:
          type: string
        author_id:
          type: string
        subject_id:
          type: string
        subject_alias:
          type: string
        title:
          type: string
        description:
          type: string
        is_public:
          type: boolean
        date:
          type: string
        time:
          type: string
        total_quiz:
          type: integer
        limit_duration:
          type: integer
        question_listings:
          type: array
          items:
            $ref: "#/components/schemas/QuizQuestion"
    NotFoundResponse:
      type: object
      properties:
        message:
          type: string
          example: Quiz not found

    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
        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]
        options:
          type: array
          items:
            type: string
          nullable: true
          example: null
        answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
        is_correct:
          type: boolean
          example: true
        time_spent:
          type: number
          format: float
          example: 8.0

    AnswerDetailData:
      type: object
      properties:
        answer_id:
          type: string
        quiz_id:
          type: string
        title:
          type: string
        description:
          type: string
        author_id:
          type: string
        answered_at:
          type: string
          example: 17-May-2025
        total_correct:
          type: integer
        total_score:
          type: integer
        total_solve_time:
          type: number
        question_listings:
          type: array
          items:
            $ref: "#/components/schemas/AnsweredQuestion"

    AnsweredQuestion:
      type: object
      properties:
        index:
          type: integer
        question:
          type: string
        type:
          type: string
          enum: [fill_the_blank, true_false, option]
        target_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
        user_answer:
          oneOf:
            - type: string
            - type: boolean
            - type: integer
        is_correct:
          type: boolean
        time_spent:
          type: number
        options:
          type: array
          items:
            type: string
          nullable: true

    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