From 9c1793088a6e767c1dab120c1661d2d9eb3c7715 Mon Sep 17 00:00:00 2001 From: akhdanre Date: Sat, 24 May 2025 14:13:34 +0700 Subject: [PATCH] feat: adding docuemntation --- app/blueprints/history.py | 4 +- docs/rest_api_docs.yaml | 945 +++++++++++++++++++++++++++++++++----- 2 files changed, 839 insertions(+), 110 deletions(-) diff --git a/app/blueprints/history.py b/app/blueprints/history.py index b711025..9d3d381 100644 --- a/app/blueprints/history.py +++ b/app/blueprints/history.py @@ -17,8 +17,10 @@ def user_history( @history_blueprint.route("/detail/", methods=["GET"]) @inject def user_detail_history( - answer_id, controller: HistoryController = Provide[Container.history_controller] + answer_id: str, + controller: HistoryController = Provide[Container.history_controller], ): + print(answer_id) return controller.get_detail_quiz_history(answer_id) diff --git a/docs/rest_api_docs.yaml b/docs/rest_api_docs.yaml index 032c653..b9dbe6b 100644 --- a/docs/rest_api_docs.yaml +++ b/docs/rest_api_docs.yaml @@ -6,9 +6,9 @@ info: servers: - url: http://127.0.0.1:5000/api/v1 - description: local server + description: Local Server - url: http://api.example.com/api/v1 - description: prduction server + description: Production Server tags: - name: Auth @@ -17,95 +17,117 @@ tags: description: User data endpoints - name: Quiz description: Quiz endpoints + # - name: Answer + - name: History + - name: Subject paths: /login: post: summary: Login - description: Login to the application - tags: - - Auth + tags: [Auth] requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - email: - type: string - example: "oukenzeumasio@gmail.com" - password: - type: string - example: "rahasia" + $ref: "#/components/requestBodies/LoginRequest" responses: "200": - description: OK - content: - application/json: - schema: - type: object - properties: - token: - type: string - example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIiwiZXhwIjoxNjIwNzQwNjY3LCJlbWFpbCI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIn0.7" + $ref: "#/components/responses/AuthTokenResponse" "400": - description: Bad Request - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: "Invalid email or password" + $ref: "#/components/responses/BadRequestLogin" /login/google: post: summary: Login with Google - description: Login to the application using Google - tags: - - Auth + 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: - type: object - properties: - token_id: - type: string - example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIiwiZXhwIjoxNjIwNzQwNjY3LCJlbWFpbCI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIn0.7" + $ref: "#/components/schemas/QuizCreateRequest" responses: - "200": - description: OK + "201": + description: Quiz created successfully content: application/json: schema: type: object properties: - token: + message: type: string - example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIiwiZXhwIjoxNjIwNzQwNjY3LCJlbWFpbCI6Im91a2VuemV1bWFzaW9AZ21haWwuY29tIn0.7" + example: Quiz created successfully + quiz_id: + type: string + example: "60f6c2d2e1f1c4567a123abc" "400": description: Bad Request content: application/json: schema: - type: object - properties: - message: - type: string - example: "Invalid token" - /logout: - post: - summary: Logout - description: Logout from the application - tags: - - Auth + $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: OK + description: Quiz found content: application/json: schema: @@ -113,14 +135,150 @@ paths: properties: message: type: string - example: "Logout successfully" + example: Quiz Found + data: + $ref: "#/components/schemas/QuizDetails" + meta: + type: object + "404": + description: Quiz not found + content: + application/json: + schema: + $ref: "#/components/schemas/NotFoundResponse" - /register: + /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: Register - description: Register to the application - tags: - - User + summary: Generate labeling quiz from passage + description: Generate quiz-style labeled data from a given historical passage + tags: [Quiz] requestBody: required: true content: @@ -128,21 +286,13 @@ paths: schema: type: object properties: - email: + sentence: type: string - example: "oukenzeumasio@gmail.com" - password: - type: string - example: "rahasia" - name: - type: string - example: "Oukenze" - birth_date: - type: string - example: "09-09-1999" + example: > + Ratu Sima adalah penguasa di Kerajaan Kalingga. Ia digambarkan sebagai seorang pemimpin wanita yang tegas dan taat terhadap peraturan... responses: "200": - description: OK + description: Successfully labeled the quiz data content: application/json: schema: @@ -150,45 +300,53 @@ paths: properties: message: type: string - example: "User created successfully" - "409": + example: succes labeling + data: + type: array + items: + $ref: "#/components/schemas/LabeledQuestion" + + "400": description: Bad Request content: application/json: schema: - type: object - properties: - message: - type: string - example: "Email already registered" - /user: - get: - summary: Get User - description: Get user data - tags: - - User + $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: OK + description: Answers submitted successfully content: application/json: schema: type: object properties: - id: - type: integer - example: 1 - name: + message: type: string - example: "Oukenze" - email: - type: string - example: "oukenzeumasio" - put: - summary: Update User - description: Update user data - tags: - - User + 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: @@ -196,12 +354,15 @@ paths: schema: type: object properties: - email: + session_id: type: string - example: "" + example: 682a26b3bedac6c20a215452 + user_id: + type: string + example: 680f0e63180b5c19b3751d42 responses: "200": - description: OK + description: Successfully retrieved the answer content: application/json: schema: @@ -209,5 +370,571 @@ paths: properties: message: type: string - example: "User updated successfully" - + 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: + 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: + 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