oas3.yaml

openapi: 3.0.0
info:
  version: "0.2.1"
  title: "Cavoke"
  description: "API for cavoke interaction between main server and clients"
servers:
  - url: "localhost:8080"
  - url: "https://develop.api.cavoke.wlko.me"
paths:
  /health:
    get:
      summary: "Simple health check"
      operationId: health
      responses:
        "200":
          description: "OK"
          content:
            text/plain:
              schema:
                type: string
                example: OK
  /games/list:
    get:
      summary: "List available games to play"
      operationId: listGames
      responses:
        "200":
          description: "List of available games as metadata"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GameInfo"
                example:
                  - id: tictactoe
                    display_name: Tic-Tac-Toe
                    description: "A paper-and-pencil game for two players who take turns marking the spaces in a three-by-three grid with X or O"
                    players_num: 2
                  - id: codenames
                    display_name: "Codenames Game"
                    description: "Two teams compete by each having a 'spymaster' give one-word clues that can point to multiple words on the board"
                    players_num: 4
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /games/{game_id}/get_config:
    get:
      summary: "Get GameInfo of specific game"
      operationId: configGame
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "String id of the game to get"
          example: tictactoe
      responses:
        "200":
          description: "Config of an existing game"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GameInfo"
        "404":
          description: "No such game"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /games/{game_id}/get_client:
    get:
      summary: "Download QML client zip of a game"
      operationId: downloadClient
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "String id of the game to get"
          example: "tictactoe"
      responses:
        "200":
          description: "Client zip file of an existing game"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: "No such game"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /play/{session_id}/send_move:
    post:
      summary: "Send a move from QML game"
      operationId: sendMove
      parameters:
        - in: path
          name: session_id
          schema:
            $ref: "#/components/schemas/SessionId"
          required: true
          example: 83896dd5-6f03-4805-8cf1-03ce6bd6077f
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      requestBody:
        description: Game move data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GameMove"
      security:
        - oauth_auth0:
            - identity
            - sessions
      responses:
        "200":
          description: "Move accepted"

        "404":
          description: "No such session / no such user"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /play/{session_id}/get_state:
    get:
      summary: "Get state for user from QML game"
      operationId: getUpdate
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully found state for user"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GameState"
        "404":
          description: "No such session / no such user"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/create:
    post:
      summary: "Create a session (room to game pair) from requested cavoke game"
      operationId: createSession_
      parameters:
        - in: query
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "String id of the game to get"
          example: tictactoe
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Created successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
        "400":
          description: "Bad request"
        "404":
          description: "No game with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/join:
    post:
      summary: "Join a session"
      operationId: joinSession
      parameters:
        - in: path
          name: session_id
          schema:
            $ref: "#/components/schemas/SessionId"
          required: true
          description: "Session Id"
        - in: query
          name: position
          schema:
            type: integer
            format: int32
            example: 1
          required: false
          description: "Position to join"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Joined successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
        "404":
          description: "No session with such id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/validate:
    post:
      summary: "Check if the host can launch the game with current config"
      operationId: validateSession
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Validation performed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationResult"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No session with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/get_info:
    get:
      summary: "Session information"
      operationId: sessionInfo
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "successfully got the info"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No session with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/start:
    post:
      summary: "Start the game"
      operationId: startSession
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully started the game"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No session with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/leave:
    post:
      summary: "Leave the session"
      operationId: leaveSession
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully left the session"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No session with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /sessions/{session_id}/change_role:
    post:
      summary: "Change user's role in session"
      operationId: changeRole
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: "UUID of a game session (room to game pair)"
        - in: query
          name: new_role
          schema:
            type: integer
            format: int32
          example: 0
          required: true
          description: "New role to join"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully changed the role in session"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No session with such game id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/{room_id}/get_info:
    get:
      summary: "Room information"
      operationId: roomInfo
      parameters:
        - in: path
          name: room_id
          schema:
            $ref: "#/components/schemas/RoomId"
          required: true
          description: "UUID of a room"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully got the info"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoomInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No room with such room id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/get_info_by_invite_code:
    get:
      summary: "Room information by invite code"
      operationId: roomInfoByCode
      parameters:
        - in: query
          name: invite_code
          schema:
            $ref: "#/components/schemas/InviteCode"
          required: true
          description: "Invite code"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully got the info"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoomInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No room with such invite code"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/create:
    post:
      summary: "Creates a new room"
      operationId: roomCreate
      parameters:
        - in: query
          name: display_name
          schema:
            type: string
          required: true
          description: "Name of a room"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully created a new room"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoomInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/join:
    post:
      summary: "Join the room by invite code"
      operationId: roomJoin
      parameters:
        - in: query
          name: invite_code
          schema:
            $ref: "#/components/schemas/InviteCode"
          required: true
          description: "Invite code"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully joined the room"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoomInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No room with such invite code"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/{room_id}/leave:
    post:
      summary: "Leave the room"
      operationId: roomLeave
      parameters:
        - in: path
          name: room_id
          schema:
            $ref: "#/components/schemas/RoomId"
          required: true
          description: "UUID of a room"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully left the info"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No room with such room id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /rooms/{room_id}/create_session:
    post:
      summary: "Create a new session inside the room"
      operationId: roomNewSession
      parameters:
        - in: path
          name: room_id
          schema:
            $ref: "#/components/schemas/RoomId"
          required: true
          description: "UUID of a room"
        - in: query
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "String id of the game to get"
          example: tictactoe
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully created a session"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No room with such room id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - sessions
  /profile/get_me:
    get:
      summary: Gets information about current user
      parameters:
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "successfully got the info"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - profile
  /profile/change_name:
    post:
      summary: Changes name for the current user
      parameters:
        - in: query
          name: new_name
          description: New user display name
          example: John Smith
          schema:
            type: string
          required: true
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "successfully changed the name"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - profile
  /users/get_user:
    get:
      summary: Gets information about given user by user_id
      parameters:
        - in: query
          name: req_user_id
          description: User id of the user to get infromation about (warning! not user_id)
          example: github|123456
          schema:
            $ref: "#/components/schemas/UserId"
          required: true
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "successfully changed the name"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "404":
          description: "Not Found"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
            - identity
            - users
  /statistics/game/{game_id}:
    get:
      summary: "Game statistics"
      operationId: gameStatistics
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "Game Id"
      responses:
        "200":
          description: "Successfully got the statistics"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GameStatistics"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No game with such id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /statistics/user/{user_id}:
    get:
      summary: "User statistics"
      operationId: userStatistics
      parameters:
        - in: path
          name: user_id
          schema:
            $ref: "#/components/schemas/UserId"
          required: true
          description: "User id"
      responses:
        "200":
          description: "Successfully got the statistics"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserStatistics"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No game with such id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /statistics/user/{user_id}/game/{game_id}:
    get:
      summary: "UserGame statistics"
      operationId: userGameStatistics
      parameters:
        - in: path
          name: user_id
          schema:
            $ref: "#/components/schemas/UserId"
          required: true
          description: "User id"
        - in: path
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "Game id"
      responses:
        "200":
          description: "Successfully got the statistics"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGameStatistics"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No game with such id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /profile/my_user_statistics:
    get:
      summary: "User statistics for currently logged in user (via auth)"
      operationId: userAuthStatistics
      parameters:
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully got the statistics"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserStatistics"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
          - identity
  /profile/my_user_game_statistics/{game_id}:
    get:
      summary: "UserGame statistics for currently logged in user (via auth)"
      operationId: userGameAuthStatistics
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: "#/components/schemas/GameId"
          required: true
          description: "Game id"
        - in: query
          name: user_id
          description: "Debug query parameter for passing user_id without JWT Auth. Not used in production."
          schema:
            $ref: "#/components/schemas/UserId"
          required: false
          example: 76376d47-c5fa-4aa2-9497-0ddadcbfc5fd
      responses:
        "200":
          description: "Successfully got the statistics"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGameStatistics"
        "400":
          description: "Bad request"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "No game with such id"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - oauth_auth0:
          - identity
  /submit_game:
    post:
      summary: "Send a game for review to the cavokedev"
      operationId: submitGame
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                game_id:
                  type: string
                display_name:
                  type: string
                description:
                  type: string
                upload_type:
                  type: string
                  enum: [ "Git Repository", "Zip Archive" ]
                git_repo:
                  type: string
                client_zip:
                  type: string
                  format: binary
                server_zip:
                  type: string
                  format: binary
      responses:
        "200":
          description: "Successfully submitted"
        "400":
          description: "Bad request"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    GameInfo:
      type: object
      description: "Metadata about specific cavoke game (e.g. tictactoe, codenames)"
      required:
        - id
        - display_name
        - description
        - players_num
        - role_names
      properties:
        id:
          $ref: "#/components/schemas/GameId"
        display_name:
          type: string
          description: "Game name displayed to users"
          example: "Tic-Tac-Toe"
        description:
          type: string
          description: "Game description displayed to users"
          example: "A paper-and-pencil game for two players who take turns marking the spaces in a three-by-three grid with X or O"
        players_num:
          type: integer
          format: int32
          description: "Maximum (?) number of players in a session"
          example: 2
        role_names:
          type: array
          items:
            type: string
          description: "Display names for all available roles (size must be equal to players_num)"
          example: [ "crosses", "noughts" ]
    GameMove:
      type: object
      description: "Information about a move made by user (e.g. placement of an X in tictactoe)"
      properties:
        move:
          type: string
          description: "Any information about the move supplied by QML. May be any string (e.g. JSON)"
          example: '{"action": "x_move", x: 1, y: 1}'
      required:
        - move
    GameState:
      type: object
      description: "Information about external state sent from server (e.g. cards on the table, moves of other players)"
      properties:
        state:
          type: string
          description: "Any state information supplied by app's logic. May be any string (e.g. JSON)"
          example: "XOO O OXO"
      required:
        - state
    RoomInfo:
      type: object
      description: "Metadata about a room"
      properties:
        room_id:
          $ref: "#/components/schemas/RoomId"
        display_name:
          type: string
          example: "My Room"
        invite_code:
          $ref: "#/components/schemas/InviteCode"
        session_id:
          $ref: "#/components/schemas/SessionId"
        host_id:
          $ref: "#/components/schemas/UserId"
        members:
          type: array
          items:
            $ref: "#/components/schemas/User"
          description: "All users present in this room"
      required:
        - room_id
        - display_name
        - invite_code
        - host_id
        - members
    User:
      type: object
      description: ""
      properties:
        user_id:
          $ref: "#/components/schemas/UserId"
        display_name:
          type: string
          example: John Smith
      required:
        - user_id
        - display_name
    Player:
      type: object
      description: "User in specific game with player_id"
      properties:
        player_id:
          type: integer
          format: int32
          example: 0
        user:
          $ref: "#/components/schemas/User"
      required:
        - player_id
        - user
    SessionCreationRequest:
      type: object
      properties:
        game_id:
          $ref: "#/components/schemas/GameId"
        game_configuration:
          type: string
          description: "Settings for the game. For instance, players count, grid size, etc."
          example: '{"grid_size": 3, "singleplayer": true}'
        players:
          type: array
          items:
            $ref: "#/components/schemas/Player"
      required:
        - game_id
        - game_configuration
        - players
    SessionStatus:
      description: "0 - NOT STARTED; 1 - RUNNING; 2 - FINISHED"
      type: integer
      format: int32
      example: 1
    SessionInfo:
      type: object
      description: "Metadata about a session (room to game pair)"
      properties:
        session_id:
          $ref: "#/components/schemas/SessionId"
        game_id:
          $ref: "#/components/schemas/GameId"
        status:
          $ref: "#/components/schemas/SessionStatus"
        host_id:
          $ref: "#/components/schemas/UserId"
        players:
          type: array
          items:
            $ref: "#/components/schemas/Player"
      required:
        - session_id
        - game_id
        - players
        - host_id
        - status
    UserId:
      type: string
      description: "User identifier from auth engine"
      example: github|123456
    GameId:
      type: string
      example: tictactoe
      description: "cavoke game unique id"
    RoomId:
      type: string
      format: uuid
      example: b2dbce0f-ceef-4bdc-b4af-5199139044e2
    SessionId:
      type: string
      format: uuid
      example: 83896dd5-6f03-4805-8cf1-03ce6bd6077f
    InviteCode:
      type: string
      pattern: '^\d{6}$'
      example: "239566"
    OccupiedPositions:
      type: object
      example: '{"max_players": 4, "players": [{"position": 1, "user_id": "github|123456"},{"position": 0, "user_id": "email|roger@example.org"}]}'
      properties:
        max_players:
          type: integer
          format: int32
          example: 4
        occupied:
          type: array
          items:
            $ref: "#/components/schemas/Player"
    ValidationResult:
      type: object
      example: '{"success": false, "message": "Not enough players"}'
      properties:
        success:
          type: boolean
        message:
          type: string
          example: "Not enough players"
      required:
        - success
    GameStatistics:
      type: object
      description: "Statistics on a specific game"
      properties:
        average_duration_sec:
          type: integer
          format: int32
          example: 35
        average_players_count:
          type: integer
          format: int32
          example: 3
        total_time_played_sec:
          type: integer
          format: int32
          example: 3600000
        total_games_played:
          type: integer
          format: int32
          example: 100345
    UserStatistics:
      type: object
      description: "Statistics on a specific user"
      properties:
        total_time_played_sec:
          type: integer
          format: int32
          example: 144
        total_games_played:
          type: integer
          format: int32
          example: 164
    UserGameStatistics:
      type: object
      description: "Statistics on a specific user in a specific game"
      properties:
        game_id:
          type: string
          example: "tictactoe"
        time_played_sec:
          type: integer
          format: int32
          example: 3600
        games_played:
          type: integer
          format: int32
          example: 3
        win_rate:
          type: number
          example: 0.7
    Error:
      type: object
      description: "General error result"
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          example: 31
        message:
          type: string
          example: "Something went wrong"
  securitySchemes:
    cavoke_oauth_auth0: # <---- arbitrary name
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
      flows:
        authorizationCode: # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
          authorizationUrl: https://cavoke.eu.auth0.com/authorize
          tokenUrl: https://cavoke.eu.auth0.com/oauth/token
          scopes:
            identity: identify as current user
            sessions: perform operations with sessions
            profile: read/write information about current user
            users: read public information about other users
#security:
#  -