diff --git a/api_doc.yml b/api_doc.yml new file mode 100644 index 0000000..db5e2eb --- /dev/null +++ b/api_doc.yml @@ -0,0 +1,470 @@ +openapi: 3.0.0 +info: + title: Truth Inquiry + description: "Serious Game sur le theme de la communication non verbale" + version: 1.0.0 + contact: + email: contact@simailadjalim.fr + license: + name: MIT + url: https://www.mit.edu/~amini/LICENSE.md + +servers: + - url: truthInquiry.simailadjalim.fr + +# Definition des tags ------------------------ +tags: + - name: "pages" + description: "Pages endpoints" + - name: "api" + description: "Api endpoints" + +# Endpoints +paths: + /: + get: + tags: + - pages + summary: "Main page" + description: "Home page of the game, it serves as a hub of all other pages : legal mentions, credits and game pages" + operationId: homePage + responses: + "200": + description: "return the home page of the game" + content: + text/html: {} + + /solo: + get: + tags: + - pages + summary: "solo game page" + description: "Sigle player game page, it holds all of the game logic from the player entering their username to the end of the game" + operationId: singlePage + responses: + "200": + description: "returns the game page" + content: + text/html: {} + + /multi: + get: + tags: + - pages + summary: "multiplayer game page" + description: "Multi player game page, it holds all of the game logic from the game creator starting the game to its end" + operationId: multiPage + responses: + "200": + description: "returns the game page" + content: + text/html: {} + + /legal: + get: + tags: + - pages + summary: "legal mention page" + description: "The legal mention page, holds the legal mentions such as where is hosted the website and who made it" + operationId: mentionLegales + responses: + "200": + description: "returns the legal mention page" + content: + text/html: {} + + /lobby/{game_id}: + get: + tags: + - pages + summary: "multiplayer lobby room" + description: "The multiplayer lobby room is shown before a multiplayer game starts, is shows the current member of the game, it is reacheable by the game id shown in the page and in the url" + parameters: + - in: path + name: game_id + schema: + type: string + required: true + description: gameId + + + operationId: invite + responses: + "200": + description: "return the lobby page." + content: + text/html: {} + "404": + description: "This does not exist or does not exist anymore" + content: + text/html: {} + + # Api ------------------------ + + /api/v1/createGame: + post: + tags: + - api + summary: "Create a game session" + description: "This endpoint create a game in the server, the username passed as parametter is set as the game owner" + operationId: create_game + requestBody: + description: "username to set as game owner" + required: true + content: + application/json: + schema: + type: object + properties: + username: + $ref: "#/components/schemas/username" + + responses: + "200": + description: "Returns a object, with the error code, and a game_id." + content: + application/json: + schema: + $ref: "#/components/schemas/newGameData" + text/plain; charset=utf-8: + schema: + type: string + + /api/v1/joinGame: + post: + tags: + - api + summary: "Adds user to an existing game" + description: "This endpoint adds the username passed as parameter to the game identified by its game_id also passed as the parametter" + operationId: join_game + requestBody: + description: "object with a game_id and a username" + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/joinGameData" + + responses: + "200": + description: "returns a object with the error code." + content: + application/json: + schema: + type: object + properties: + error: + $ref: "#/components/schemas/error" + text/plain; charset=utf-8: + schema: + type: string + + /api/v1/isOwner: + post: + tags: + - api + summary: "ask if the user is the game owner" + description : "This endpoint it used to know if the username stored in the cookie is the owner of the game" + operationId: is_owner + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + responses: + "200": + description: "returns an object with the error code." + content: + application/json: + schema: + type: object + properties: + error: + $ref: "#/components/schemas/error" + owner: + type: boolean + description: "boolean determining if the palyer is the owner of the gzame" + + /api/v1/startGame: + post: + tags: + - api + summary: "Start the game" + description: "Starts the game and generate necessary data" + operationId: startGame + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + + responses: + "200": + description: "returns a object with the error code." + content: + application/json: + schema: + type: object + properties: + error: + $ref: "#/components/schemas/error" + + /api/v1/getGameData: + post: + tags: + - api + summary: "get game data" + description: "Guess the game from the cookie and returns general game data necessary to the client to work properly" + operationId: getGame + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + responses: + "200": + description: "returns a object with the error code." + content: + application/json: + schema: + $ref: "#/components/schemas/gameData" + + /api/v1/getGameMembers: + post: + tags: + - api + summary: "Get game members" + description: "Guess the game from the cookie and returns the members of that game" + operationId: getMembers + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + responses: + "200": + description: "List of members in the game" + content: + application/json: + schema: + type: object + properties: + "error": + $ref: "#/components/schemas/error" + "members": + type: array + items: + type: string + + /api/v1/hasJoined: + post: + tags: + - api + summary: "Check if the player is in a given game" + description: "Checks the cookie to see if the client is currently in a given game" + operationId: has_joined + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + responses: + "200": + description: "Returns error code and a boolean determining if the player is in the game" + content: + application/json: + schema: + type: object + properties: + "error": + $ref: "#/components/schemas/error" + "joined": + type: boolean + + /api/v1/getNpcImage: + post: + tags: + - "api" + summary: Get an image from its ID + description: > + This endpoint is used to show NPC images in the result page. The image id is provided by the server upon + finishing the game. a static ID is needed because the server delete information related to the game after finishing it + operationId: get_npc_image + requestBody: + description: "image_id we want the image of" + required: true + content: + application/json: + schema: + type: object + properties: + image_id: + type: integer + responses: + "200": + description: "image" + content: + image/png: + schema: + type: string + + /api/v1/getNpcReaction: + post: + tags: + - api + summary: "Get an image corresponding to the reaction of a NPC in this game" + description: "This endpoint is used during the game to get a random image corresponding to the assigned reaction of a NPC. The image may change every request" + operationId: get_npc_reaction + parameters: + - in: cookie + name: session + description: Local session, holds data used to authentificate the user and the games they belong. + required: true + schema: + type: object + requestBody: + description: "ID of the NPC we want to get the image of" + required: true + content: + application/json: + schema: + type: object + properties: + npcid: + type: integer + responses: + "200": + description: "image" + content: + image/png: + schema: + type: string + #/api/v1/gameProgress + #/api/v1/submitAnwers + + +components: #---------------------------------- + schemas: + error: + type: integer + description: "request error code" + enum: + - 0 + - 1 + + game_id: + type: string + description: "ID of the game" + + username: + type: string + description: "player username" + + npc: + type: object + description: "npc to interogate in the game" + properties: + "QA_0" : + type: string + description: "'Where?' type answer" + "QA_1" : + type: string + description: "'With who?' type answer" + name: + type: string + description: "npc name" + + salle: + type: object + description: "object representing a single room the the game story" + properties: + name: + type: string + description: virtual room name + npcs: + type: array + description: array of the npc_id present in the room, should always be at the number of two, execept for the bulgar who was alone in the room + items: + type: string + #____________________________# + + game: + type: object + description: "Main game data, should be queried once" + properties: + npcs: + type: object + description: "List of the randomly chosen npc, with their answer for each type of questions" + properties: + "npc_id_0": + $ref: "#/components/schemas/npc" + "npc_id_1": + $ref: "#/components/schemas/npc" + "npc_id_2": + $ref: "#/components/schemas/npc" + "npc_id_3": + $ref: "#/components/schemas/npc" + "npc_id_4": + $ref: "#/components/schemas/npc" + questions: + type: object + description: "Question identified by their type, randomly chosen by the server" + properties: + "QA_0": + type: string + description: "'Where?' type question" + "QA_1": + type: string + description: "'With who?' type question" + rooms: + type: object + description: "object storing the virtual rooms that holds the npcs" + properties: + "room_id_0": + $ref: "#/components/schemas/salle" + "room_id_1": + $ref: "#/components/schemas/salle" + "room_id_2": + $ref: "#/components/schemas/salle" + traits: + type : array + description: "List of available traits on in this game session" + items: + type: string + + newGameData: + type: object + properties: + error: + $ref: "#/components/schemas/error" + game_id: + $ref: "#/components/schemas/game_id" + + + joinGameData: + type: object + properties: + game_id: + $ref: "#/components/schemas/game_id" + username: + $ref: "#/components/schemas/username" + + gameData: + type: object + properties: + error: + $ref: "#/components/schemas/error" + gameData: + $ref: "#/components/schemas/game" + + diff --git a/truthinquiry/routes/routes_api.py b/truthinquiry/routes/routes_api.py index b2d5f76..a678df1 100644 --- a/truthinquiry/routes/routes_api.py +++ b/truthinquiry/routes/routes_api.py @@ -9,6 +9,8 @@ from truthinquiry.logic import game_logic routes_api = flask.Blueprint("api", __name__) +# API specification is documented in api_doc.yml + @routes_api.route("/createGame", methods=["GET", "POST"]) def create_game(): username = flask.request.values.get("username") diff --git a/truthinquiry/templates/doc.html b/truthinquiry/templates/doc.html index cedc029..ab367ff 100644 --- a/truthinquiry/templates/doc.html +++ b/truthinquiry/templates/doc.html @@ -691,7 +691,7 @@ var defs = {} defs["error"] = { "type" : "integer", - "description" : "error de la requette", + "description" : "request error code", "enum" : [ 0, 1 ] }; defs["game"] = { @@ -708,13 +708,13 @@ }, "traits" : { "type" : "array", - "description" : "liste des traits disponible pour cette session de jeu", + "description" : "List of available traits on in this game session", "items" : { "type" : "string" } } }, - "description" : "données du jeu" + "description" : "Main game data, should be queried once" }; defs["gameData"] = { "type" : "object", @@ -729,7 +729,7 @@ }; defs["game_id"] = { "type" : "string", - "description" : "id de la room multijoueur" + "description" : "ID of the game" }; defs["game_npcs"] = { "type" : "object", @@ -750,21 +750,21 @@ "$ref" : "#/components/schemas/npc" } }, - "description" : "liste des personnages choisis par le serveur de maniere aleatoire, ainsi que leur texte de dialogue" + "description" : "List of the randomly chosen npc, with their answer for each type of questions" }; defs["game_questions"] = { "type" : "object", "properties" : { "QA_0" : { "type" : "string", - "description" : "question de type \"oû etait le personnage ?\"" + "description" : "'Where?' type question" }, "QA_1" : { "type" : "string", - "description" : "question de type \"avec qui etait le personnage ?\"" + "description" : "'With who?' type question" } }, - "description" : "les questions identifiés par leur type, choisis aleatoirement par le serveur" + "description" : "Question identified by their type, randomly chosen by the server" }; defs["game_rooms"] = { "type" : "object", @@ -776,10 +776,10 @@ "$ref" : "#/components/schemas/salle" }, "room_id_2" : { - "$ref" : "#/components/schemas/salle_" + "$ref" : "#/components/schemas/salle" } }, - "description" : "object contenant les salle virtuelle de la partie indentifiées par leur identifiants" + "description" : "object storing the virtual rooms that holds the npcs" }; defs["inline_response_200"] = { "type" : "object", @@ -797,7 +797,7 @@ }, "owner" : { "type" : "boolean", - "description" : "booleen determinant si le joueur est le createur de la partie" + "description" : "boolean determining if the palyer is the owner of the gzame" } } }; @@ -853,56 +853,39 @@ "properties" : { "QA_0" : { "type" : "string", - "description" : "reponse a la question \"oû ce personnage etait ?\"" + "description" : "'Where?' type answer" }, "QA_1" : { "type" : "string", - "description" : "reponse a la question \"avec qui ce personnage etait ?\"" + "description" : "'With who?' type answer" }, "name" : { "type" : "string", - "description" : "nom du personnage" + "description" : "npc name" } }, - "description" : "personnage a interroger dans la partie" + "description" : "npc to interogate in the game" }; defs["salle"] = { "type" : "object", "properties" : { "name" : { "type" : "string", - "description" : "nom de la salle virtuelle" + "description" : "virtual room name" }, "npcs" : { "type" : "array", - "description" : "array contenant les identifiants des personnage present dans la salle, cet array contient toujours deux identifiants sauf dans le cas du coupable ou il est seul.", + "description" : "array of the npc_id present in the room, should always be at the number of two, execept for the bulgar who was alone in the room", "items" : { "type" : "string" } } }, - "description" : "object representant une salle virtuelle pour l'intrigue textuelle du jeu" -}; - defs["salle_"] = { - "type" : "object", - "properties" : { - "name" : { - "type" : "string", - "description" : "nom de la salle virtuelle" - }, - "npcs" : { - "type" : "array", - "description" : "array contenant les identifiants des personnage present dans la salle, cet array contient toujours deux identifiants sauf dans le cas du coupable ou il est seul.", - "items" : { - "type" : "integer" - } - } - }, - "description" : "object representant une salle virtuelle pour l'intrigue textuelle du jeu" + "description" : "object representing a single room the the game story" }; defs["username"] = { "type" : "string", - "description" : "pseudo du joueur" + "description" : "player username" }; defs["v1_createGame_body"] = { "type" : "object", @@ -915,7 +898,7 @@ defs["v1_getNpcImage_body"] = { "type" : "object", "properties" : { - "npcid" : { + "image_id" : { "type" : "integer" } } @@ -979,6 +962,9 @@
  • invite
    • +
  • + mentionLegales +
  • multiPage
    • @@ -1010,12 +996,12 @@

    createGame

    -

    Demande une nouvelle session de jeu multijoueur au serveur

    +

    Create a game session

    -

    Cette route crée une salle de jeu multijoueur dans le serveur, elle octroie ensuite les droit de creation de la salle a l'utilisateur dont le pseudo est donné en parametre post et lui retourne l'identifiant de la game

    +

    This endpoint create a game in the server, the username passed as parametter is set as the game owner


    /api/v1/createGame
    @@ -1057,7 +1043,7 @@ public class ApiApiExample { public static void main(String[] args) { ApiApi apiInstance = new ApiApi(); - V1_createGame_body body = ; // V1_createGame_body | Le pseudo de la personne souhaitant crée une partie + V1_createGame_body body = ; // V1_createGame_body | username to set as game owner try { newGameData result = apiInstance.createGame(body); System.out.println(result); @@ -1076,7 +1062,7 @@ public class ApiApiExample { public static void main(String[] args) { ApiApi apiInstance = new ApiApi(); - V1_createGame_body body = ; // V1_createGame_body | Le pseudo de la personne souhaitant crée une partie + V1_createGame_body body = ; // V1_createGame_body | username to set as game owner try { newGameData result = apiInstance.createGame(body); System.out.println(result); @@ -1092,11 +1078,11 @@ public class ApiApiExample { 
    Coming Soon!
    -->
    - 
    V1_createGame_body *body = ; // Le pseudo de la personne souhaitant crée une partie
+                              
    V1_createGame_body *body = ; // username to set as game owner
 
 ApiApi *apiInstance = [[ApiApi alloc] init];
 
-// Demande une nouvelle session de jeu multijoueur au serveur
+// Create a game session
 [apiInstance createGameWith:body
               completionHandler: ^(newGameData output, NSError* error) {
                             if (output) {
@@ -1113,7 +1099,7 @@ ApiApi *apiInstance = [[ApiApi alloc] init];
                               
    var TruthInquiry = require('truth_inquiry');
 
 var api = new TruthInquiry.ApiApi()
-var body = ; // {{V1_createGame_body}} Le pseudo de la personne souhaitant crée une partie
+var body = ; // {{V1_createGame_body}} username to set as game owner
 
 var callback = function(error, data, response) {
   if (error) {
@@ -1144,11 +1130,11 @@ namespace Example
         {
 
             var apiInstance = new ApiApi();
-            var body = new V1_createGame_body(); // V1_createGame_body | Le pseudo de la personne souhaitant crée une partie
+            var body = new V1_createGame_body(); // V1_createGame_body | username to set as game owner
 
             try
             {
-                // Demande une nouvelle session de jeu multijoueur au serveur
+                // Create a game session
                 newGameData result = apiInstance.createGame(body);
                 Debug.WriteLine(result);
             }
@@ -1167,7 +1153,7 @@ namespace Example
 require_once(__DIR__ . '/vendor/autoload.php');
 
 $api_instance = new Swagger\Client\ApiApiApi();
-$body = ; // V1_createGame_body | Le pseudo de la personne souhaitant crée une partie
+$body = ; // V1_createGame_body | username to set as game owner
 
 try {
     $result = $api_instance->createGame($body);
@@ -1184,7 +1170,7 @@ use WWW::SwaggerClient::Configuration;
 use WWW::SwaggerClient::ApiApi;
 
 my $api_instance = WWW::SwaggerClient::ApiApi->new();
-my $body = WWW::SwaggerClient::Object::V1_createGame_body->new(); # V1_createGame_body | Le pseudo de la personne souhaitant crée une partie
+my $body = WWW::SwaggerClient::Object::V1_createGame_body->new(); # V1_createGame_body | username to set as game owner
 
 eval { 
     my $result = $api_instance->createGame(body => $body);
@@ -1204,10 +1190,10 @@ from pprint import pprint
 
 # create an instance of the API class
 api_instance = swagger_client.ApiApi()
-body =  # V1_createGame_body | Le pseudo de la personne souhaitant crée une partie
+body =  # V1_createGame_body | username to set as game owner
 
 try: 
-    # Demande une nouvelle session de jeu multijoueur au serveur
+    # Create a game session
     api_response = api_instance.create_game(body)
     pprint(api_response)
 except ApiException as e:
@@ -1232,7 +1218,7 @@ except ApiException as e: