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"