Swagger Document Enhancement

[ricksu978]

No description provided.

[allenh]

Unassigned myself as this is no longer my responsibility.
Here is the doc created initially as a first step: https://www.notion.so/waterball/GAAS-Lobby-Service-Documentation-813ec18abbbf4690ab151a516729b895?pvs=4

[allenh]

Unassigned myself as this is no longer my responsibility. Here is the doc created initially as a first step: https://www.notion.so/waterball/GAAS-Lobby-Service-Documentation-813ec18abbbf4690ab151a516729b895?pvs=4

Reposting the initial Notion documentation notes for transparency:

GAAS Lobby Service Documentation

• Error codes: PlatformError.kt
  • alphanumeric based error codes
• JWT

Game Registration Controller

• GET /games

  • list all registered games

  • 200

    • A list of games
    • Game object:

    {
    	// game id from the register - mongo object id
      "id": "string",
    	// the human readable name of the game
      "name": "string", 
    	// uri - point to external CDN
      "img": "string",
    	// minimum number of players required to start the game
      "minPlayers": 0,
    	// maximum number of players allowed to start the game
      "maxPlayers": 0
    }

  • remove 400, and 404 status

  • Game object

• POST /games

  • create games
    • input: a single JSON object that represents the game
  • game object

  {
    // English based unique name used for routing game requests to their respective resources
    // verify field validation
  	// required
    "uniqueName": "string",
  	// human readable name
    // char length 
  	// required
    "displayName": "string",
    // English description of the game
    // verify field validation 
  	// required
    "shortDescription": "string",
  	// game rule
  	// required
    "rule": "string",
    // game image URL
  	// required
    "imageUrl": "string",
  	// minimum number of players required to start the game
  	// required
    "minPlayers": 0,
  	// maximum number of players allowed to start the game
  	// required
    "maxPlayers": 0
  	// cloud hosted frontend absolute URL
  	// required
    "frontEndUrl": "string",
  	// cloud hosted backend absolute URL
  	// required
    "backEndUrl": "string"
  }

  • 200 - OK

  • 400

    • object

      {
      	"timestamp": "2023-08-18T14:10:17.545Z",
        "errorCode": "string",
        "message": "string"
      }

  • 404 - remove, will not happen

• PUT /games/{gameId}

  • Replace game config based on the supplied game id with the supplied game object in request body

  Game object (same as POST) - request body

  {
    // English based unique name used for routing game requests to their respective resources
    // verify field validation
  	// required
    "uniqueName": "string",
  	// human readable name
    // char length 
  	// required
    "displayName": "string",
    // English description of the game
    // verify field validation 
  	// required
    "shortDescription": "string",
  	// game rule
  	// required
    "rule": "string",
    // game image URL
  	// required
    "imageUrl": "string",
  	// minimum number of players required to start the game
  	// required
    "minPlayers": 0,
  	// maximum number of players allowed to start the game
  	// required
    "maxPlayers": 0
  	// cloud hosted frontend absolute URL
  	// required
    "frontEndUrl": "string",
  	// cloud hosted backend absolute URL
  	// required
    "backEndUrl": "string"
  }

  • errors: 400 - follow POST
  • 404 - when gameId is not found in the table

Health Check Controller

• GET /health
  • keep alive

OAuth2 Controller

• all endpoints are deprecated
• all login requests now will go through API gateway
  • wait for authentication documentation

Room Controller

• GET /rooms

  Query parameters

  • status
    • Enum
      • WAITING
        • waiting for players to join room
      • PLAYING
        • game room is currently
  • page
    • room pagination, page starts at 0
    • page ≥ 0
  • perPage
    • number of rooms returned per request
    • perPage ≥ 0

  Response

  • 200
  • response.body

  {
    "rooms": Room[],
    "page": PageMetadata,
  }

  Room

  {
    // mongodb objectid
    "id": "string",
    // name of the room, user defined
    "name": "string",
    // simple game object
    "game": {
  		// game id foreign key - corresponds to the registered game list
      "id": "string",
  		// game's displayName
      "name": "string"
    },
    // the player who created the room
    "host": {
  		// user id foreign key - corresponds to the user table
      "id": "string",
  		// user nickname
      "nickname": "string"
    },
    // room host defined maximum number of players
    "maxPlayers": 0,
    // room host defined minimum minimum of players
    "minPlayers": 0,
  	// the number of players currently in the room
    "currentPlayers": 0,
    // is the room locked, ie. ture iff the host makes the room private
    "isLocked": true
  }

  PageMetadata

  {
  	// the total number of rooms matching the status filter
  	"total": 0,
  	// the current page corresponding to the requests request
    "page": 0,
  	// the current page of the request
    "perPage": 0
  }

• POST /rooms

  • create room

  request.body

  {
    // room name
  	// required
    "name": "string",
  	// corresponding game id in the registered game list
  	// required
    "gameId": "string",
  	// room host defined password to enter the game
  	// optional
    "password": "string",
  	// maximum number of players for the room
  	// required
  	// validation: the room's maximum number of player cannot be more than the game's allowed maximum number of players
    "maxPlayers": 0,
  	// minimum number of players for the room
  	// required
  	// validation: the room's minimum number of player cannot be more than the game's allowed minimum number of players
    "minPlayers": 0
  }

  400 - should correspond to the validation errors

  404 - delete this

• GET /rooms/{roomId}

  • get rooms by id

  • path parameter

    • roomId: generated mongo objectId

  • response

    • 200
      • response

    {
      // mongodb objectid
      "id": "string",
      // name of the room, user defined
      "name": "string",
      // simple game object
      "game": {
    		// game id foreign key - corresponds to the registered game list
        "id": "string",
    		// game's displayName
        "name": "string"
      },
      // the player who created the room
      "host": {
    		// user id foreign key - corresponds to the user table
        "id": "string",
    		// user nickname
        "nickname": "string"
      },
    	// the players currently in the room
      "players": [
        {
          "id": "string",
          "nickname": "string"
        }
      ],
    	// room host defined maximum number of players
      "maxPlayers": 0,
      // room host defined minimum minimum of players
      "minPlayers": 0,
    	// the number of players currently in the room
      "currentPlayers": 0,
      // is the room locked, ie. ture iff the host makes the room private
      "isLocked": true
    	// Status enum: WAITING, PLAYING
      "status": "string"
    }

    • 400 - no such error
    • 404 - game id not found

• DELETE /rooms/{roomId}

  • delete room from the supplied room Id
  • path parameter - roomId
    • the generated mongodb object id for the room
  • 204 - delete success
  • 400 - validation error, only host can delete room
  • 404 - roomId not found

• POST /rooms/{roomId}/players

  • Player joining the room
  • path parameter
    • roomId: generated mongo objectId
  • request body

  {
  	// the password set by the room host
  	// optional
    "password": "string"
  }

  • 200 - success
    • the response body should not have error code
  • 400 - unable to join
    • room has reach maximum number of players set by the room host
    • the room has password and the supplied password is not correct
  • 404 - roomId not found

• DELETE /rooms/{roomId}/players/{playerId}

  • removing player from the room
  • path parameter roomId
    • room id
  • path parameter playerId
    • user id - corresponding to user table
  • 200 - success - player has been removed
    • the response body should not have error code
  • 400 - unable to remove player
    • insufficient permission - the initiated user is not room host
  • 404 - not found
    • unable to find the specified room
    • unable to find the specified player in the room

• DELETE /rooms/{roomId}/players/me

  • player self leaving the given room
  • if the player is not in the room specified by roomId the request will still succeed
  • path parameter roomId
    • room id
  • no body
  • 204 - success - player has left the room
    • the response body should not have error code
  • 404 - not found
    • unable to find the specified room

• POST /rooms/{roomId}/players/me:cancel

  • players self change status to “not ready” on the UI
  • if the player is already “not ready” and calls this endpoint the request will return 200
  • there is isReady label that’s not on the swagger doc
    • investigate getRoomViewModel
  • path parameter roomId
    • room id
  • 200 - successfully changed status to NOT_READY
  • 404 - not found
    • roomId not found

• POST /rooms/{roomId}/players/me:ready

  • players self change status to “ready” on the UI
  • if the player is already “ready” and calls this endpoint the request will return 200
  • toggle the same field as the cancel endpoint from above
  • path parameter roomId
    • room id
  • 200 - successfully changed status to NOT_READY
  • 404 - not found
    • roomId not found

User Controller

• GET /users/me

  • gets the user’s self information
  • 200 - success
    • response.body

  {
    // user id - generated mongodb objectid
  	"id": "string",
    // user email
    "email": "string",
  	// user nick name
    "nickname": "string"
  }

  • 400 - will not occur - remove
  • 404 - will not occur - remove

• PUT /users

  • user self change information
  • request.body

  {
  	// user desired new nickname
  	// uniqueness constraint
  	// character length range in [4,16]
  	// alphanumeric + zh encoding
  	"nickname": "string"
  }

  • 200 - success, in response.body

  {
    "id": "string",
    "email": "string",
    "nickname": "string"
  }

  • 400 - validation failed - see above
  • 404 - will not occur