{ "openapi": "3.0.0", "info": { "title": "3択クイズアプリ API", "description": "英語学習用の3択クイズアプリケーションのAPI仕様", "version": "1.0.0" }, "servers": [ { "url": "http://localhost:3001/api", "description": "開発環境" } ], "paths": { "/quiz/questions": { "get": { "summary": "クイズ問題を取得", "description": "指定された数のランダムなクイズ問題を取得する", "parameters": [ { "name": "count", "in": "query", "description": "取得する問題数", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "category", "in": "query", "description": "問題カテゴリでフィルタリング", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuizQuestion" } } } } } } }, "400": { "description": "不正なリクエスト", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "サーバーエラー", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quiz/session": { "post": { "summary": "クイズセッションを開始", "description": "新しいクイズセッションを作成する", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "ユーザーID(オプション)" }, "totalQuestions": { "type": "integer", "minimum": 1, "maximum": 50, "description": "総問題数" } }, "required": ["totalQuestions"] } } } }, "responses": { "201": { "description": "セッション作成成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer" }, "startedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "不正なリクエスト", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "サーバーエラー", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quiz/answer": { "post": { "summary": "回答を送信", "description": "クイズ問題への回答を送信する", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer", "description": "セッションID" }, "questionId": { "type": "integer", "description": "問題ID" }, "userAnswer": { "type": "string", "description": "ユーザーの回答" } }, "required": ["sessionId", "questionId", "userAnswer"] } } } }, "responses": { "200": { "description": "回答処理成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "isCorrect": { "type": "boolean" }, "correctAnswer": { "type": "string" }, "explanation": { "type": "string" } } } } } }, "400": { "description": "不正なリクエスト", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "セッションまたは問題が見つからない", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "サーバーエラー", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quiz/session/{sessionId}/complete": { "post": { "summary": "クイズセッションを完了", "description": "クイズセッションを完了し、結果を返す", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "セッション完了成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer" }, "totalQuestions": { "type": "integer" }, "correctAnswers": { "type": "integer" }, "accuracy": { "type": "number", "format": "float" }, "completedAt": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QuizResult" } } } } } } }, "404": { "description": "セッションが見つからない", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "サーバーエラー", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statistics": { "get": { "summary": "統計情報を取得", "description": "ユーザーの学習統計情報を取得する", "parameters": [ { "name": "userId", "in": "query", "description": "ユーザーID(オプション)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "統計情報取得成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalSessions": { "type": "integer" }, "totalQuestions": { "type": "integer" }, "totalCorrect": { "type": "integer" }, "averageAccuracy": { "type": "number", "format": "float" }, "categoryStats": { "type": "object", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "correct": { "type": "integer" }, "accuracy": { "type": "number", "format": "float" } } } }, "recentSessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "integer" }, "accuracy": { "type": "number", "format": "float" }, "completedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "サーバーエラー", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "QuizQuestion": { "type": "object", "properties": { "id": { "type": "integer" }, "category": { "type": "string" }, "japanese": { "type": "string" }, "english": { "type": "string" }, "correctAnswer": { "type": "string" } }, "required": ["id", "category", "japanese", "english", "correctAnswer"] }, "QuizResult": { "type": "object", "properties": { "id": { "type": "integer" }, "questionId": { "type": "integer" }, "userAnswer": { "type": "string" }, "isCorrect": { "type": "boolean" }, "answeredAt": { "type": "string", "format": "date-time" } }, "required": ["id", "questionId", "userAnswer", "isCorrect", "answeredAt"] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "integer" } }, "required": ["error", "message"] } } } }