Update Swagger UI Docs (#50)

pfeifferjack · web-flow · commit c5372432a415 · 2024-09-12T15:38:49.000-04:00
diff --git a/src/@types/hackthelab.d.ts b/src/@types/hackthelab.d.ts
@@ -3,7 +3,6 @@ import { Request } from "express";
 
 declare module "hackthelab" {
   /**
-   * @swagger
    * components:
    *   schemas:
    *     User:
@@ -229,7 +228,6 @@ declare module "hackthelab" {
   }
 
   /**
-   * @swagger
    * components:
    *   schemas:
    *     AllActionResponseItem:
@@ -251,7 +249,6 @@ declare module "hackthelab" {
   }
 
   /**
-   * @swagger
    * components:
    *   schemas:
    *     AdminCell:
@@ -317,7 +314,6 @@ declare module "hackthelab" {
   }
 
   /**
-   * @swagger
    * components:
    *   schemas:
    *     Award:
@@ -340,7 +336,6 @@ declare module "hackthelab" {
   }
 
   /**
-   * @swagger
    * components:
    *   schemas:
    *     Score:
@@ -359,7 +354,6 @@ declare module "hackthelab" {
   }
 
   /**
-   * @swagger
    * components:
    *   schemas:
    *     RankingResult:
diff --git a/src/controllers/maze-controller/getActions.ts b/src/controllers/maze-controller/getActions.ts
@@ -14,7 +14,6 @@ export const actionsSchema = [
 ];
 
 /**
- * @swagger
  * /v1/maze/{mazeId}/actions/{userId}:
  *   get:
  *     tags: [Maze (ADMIN)]
diff --git a/src/controllers/maze-controller/getAllActions.ts b/src/controllers/maze-controller/getAllActions.ts
@@ -4,7 +4,6 @@ import { asyncHandler } from "utils";
 import { rethrowOrCreateError } from "utils/create-error";
 
 /**
- * @swagger
  * /v1/maze/{mazeId}/actions:
  *   get:
  *     tags: [Maze (ADMIN)]
diff --git a/src/controllers/maze-controller/getMaze.ts b/src/controllers/maze-controller/getMaze.ts
@@ -6,12 +6,14 @@ import { asyncHandler } from "utils";
  * /v1/maze/{mazeId}:
  *   get:
  *     tags: [Maze (SANDBOX)]
- *     summary: Returns maze information for a given maze ID. (Sandbox only)
+ *     summary: Returns a maze's information.
+ *     description: Returns a maze's cells (with type and surroundings), cheese locations, dimensions, start and exit.
+ *                  <br><br>
+ *                  **Note** This sandbox endpoint is for testing purposes only, not all information provided is accessible during the competition.
  *     parameters:
  *       - $ref: '#/components/parameters/MazeRequestPathBase'
  *     responses:
  *       200:
- *         description: Fetch successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/maze-controller/getMazes.ts b/src/controllers/maze-controller/getMazes.ts
@@ -11,19 +11,21 @@ export const mazesSchema = [query("env").optional().isEnvironment()];
  * /v1/mazes:
  *   get:
  *     tags: [Maze]
- *     summary: Returns a list of available maze IDs.
+ *     summary: Returns a list of mazes.
+ *     description: Each maze has an ID, number of cheese count, and dimensions.
+ *       Depending on the API key used (Sandbox or Competition) the respective list of mazes will be returned.
+ *       <br><br>
+ *       **Note:** The list of competition mazes will be limited until announced.
  *     responses:
  *       200:
- *         description: Fetch successful
+ *         description: Maze list successful.
  *         content:
  *           application/json:
  *             schema:
  *               type: array
  *               items:
  *                 $ref: '#/components/schemas/MazeResponse'
  *                 type: object
- *       400:
- *         $ref: '#/components/responses/BadRequest'
  *       401:
  *         $ref: '#/components/responses/Unauthorized'
  *       403:
diff --git a/src/controllers/maze-controller/maze-controller.ts b/src/controllers/maze-controller/maze-controller.ts
@@ -12,9 +12,11 @@ import putMaze, { mazeUpdateSchema } from "./putMaze";
  * @swagger
  * tags:
  *   - name: Maze
- *     description: Maze management
+ *     description: Maze management.
  *   - name: Maze (SANDBOX)
- *     description: Maze management for sandbox
+ *     description: Maze management endpoint to be used in the sandbox environment.
+ */
+/**
  *   - name: Maze (ADMIN)
  *     description: Maze management for administrators
  */
diff --git a/src/controllers/maze-controller/putMaze.ts b/src/controllers/maze-controller/putMaze.ts
@@ -3,7 +3,6 @@ import { MazeRequest } from "hackthelab";
 import { MazeService } from "services";
 
 /**
- * @swagger
  * components:
  *   schemas:
  *     MazeUpdateRequestBody:
@@ -15,7 +14,6 @@ import { MazeService } from "services";
 export const mazeUpdateSchema = [body("locked").isBoolean().withMessage("'locked' must be provided and a boolean type.")];
 
 /**
- * @swagger
  * /v1/maze/{mazeId}:
  *   put:
  *     tags: [Maze (ADMIN)]
diff --git a/src/controllers/rat-controller/getActions.ts b/src/controllers/rat-controller/getActions.ts
@@ -7,12 +7,12 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/{mazeId}/actions:
  *   get:
  *     tags: [Rat (SANDBOX)]
- *     summary: Returns recorded actions and score for the rat in a maze.
+ *     summary: Returns the rats progress for a maze.
+ *     description: Returns the actions the rat has taken in the maze and the score.
  *     parameters:
  *       - $ref: '#/components/parameters/MazeRequestPathBase'
  *     responses:
  *       200:
- *         description: Actions successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/getSurroundings.ts b/src/controllers/rat-controller/getSurroundings.ts
@@ -8,6 +8,8 @@ import { asyncHandler } from "utils";
  *   get:
  *     tags: [Rat]
  *     summary: Returns the rat's immediate surroundings for the provided maze ID.
+ *     description: Response object includes the cell type for the rat's current position (`type`)
+ *                  and the cell type for each direction (`north`, `east`, `south`, `west`) from the rat's current position.
  *     parameters:
  *       - $ref: '#/components/parameters/MazeRequestPathBase'
  *     responses:
diff --git a/src/controllers/rat-controller/postDrop.ts b/src/controllers/rat-controller/postDrop.ts
@@ -7,7 +7,11 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/drop:
  *   post:
  *     tags: [Rat]
- *     summary: Allows the rat to drop a cheese in the maze.
+ *     summary: Attempts to drop a cheese.
+ *     description: Cheese will be dropped if the rat is holding a cheese and is currently positioned at a cell of type `EXIT`, otherwise the action will fail.
+ *                  After a cheese is successfully dropped, the rat will be free to grab another cheese.
+ *                  <br><br>
+ *                  **Note:** Cheese will not automatically be dropped when the rat exits the maze.
  *     requestBody:
  *       description: Drop request.
  *       required: true
@@ -17,7 +21,6 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  *             $ref: '#/components/schemas/MazeRequest'
  *     responses:
  *       200:
- *         description: Drop successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/postEat.ts b/src/controllers/rat-controller/postEat.ts
@@ -7,17 +7,19 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/eat:
  *   post:
  *     tags: [Rat]
- *     summary: Gives a rat the ability to eat a cheese (if already on a cheese cell).
+ *     summary: Attempts to eat a cheese.
+ *     description: Cheese will be eaten if either the rat is currently positioned at a cell of type `CHEESE` or currently holding a cheese.
+ *                  If the both are true, the cheese at the rat's current position will be eaten and the cheese held by the rat will remain.
+ *                  After a cheese is successfully eaten, the cell type will be updated to `OPEN`.
  *     requestBody:
  *       description: Eat request.
  *       required: true
  *       content:
  *         application/json:
  *           schema:
- *             $ref: '#/components/schemas/MazeRequest'
+ *             $  ref: '#/components/schemas/MazeRequest'
  *     responses:
  *       200:
- *         description: Eat successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/postExit.ts b/src/controllers/rat-controller/postExit.ts
@@ -7,7 +7,9 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/exit:
  *   post:
  *     tags: [Rat]
- *     summary: Gives a rat the ability to exit a maze.
+ *     summary: Attempts to exit a maze.
+ *     description: The rat will exit a maze if the rat is currently positioned at a cell of type `EXIT`, otherwise the action will fail.
+ *                  After the rat has exited the maze, the rat will no longer be able to perform any actions for the maze.
  *     requestBody:
  *       description: Exit request.
  *       required: true
@@ -17,7 +19,6 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  *             $ref: '#/components/schemas/MazeRequest'
  *     responses:
  *       200:
- *         description: Exit successful.
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/postGrab.ts b/src/controllers/rat-controller/postGrab.ts
@@ -7,7 +7,11 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/grab:
  *   post:
  *     tags: [Rat]
- *     summary: Allows the rat to grab a cheese in the maze.
+ *     summary: Attempts to grab a cheese.
+ *     description: Cheese will be grabbed if the rat is currently positioned at a cell of type `CHEESE` and is not already holding a cheese, otherwise the action will fail.<br>
+ *                  <br>
+ *                  After a cheese is successfully grabbed, the cell type will be updated to `OPEN`.
+ *
  *     requestBody:
  *       description: Grab request.
  *       required: true
@@ -17,7 +21,6 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  *             $ref: '#/components/schemas/MazeRequest'
  *     responses:
  *       200:
- *         description: Grab successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/postMove.ts b/src/controllers/rat-controller/postMove.ts
@@ -31,7 +31,8 @@ export const moveSchema = [
  * /v1/rat/move:
  *   post:
  *     tags: [Rat]
- *     summary: Moves a rat in a direction for a specific maze.
+ *     summary: Attempts to move in a direction.
+ *     description: The rat will move in the provided direction if the cell in that direction is not a wall, otherwise the action will fail.
  *     requestBody:
  *       description: Move request.
  *       required: true
@@ -41,7 +42,6 @@ export const moveSchema = [
  *             $ref: '#/components/schemas/MoveRequest'
  *     responses:
  *       200:
- *         description: Move successful
  *         content:
  *           application/json:
  *             schema:
diff --git a/src/controllers/rat-controller/postReset.ts b/src/controllers/rat-controller/postReset.ts
@@ -18,9 +18,9 @@ export const resetSchema = [
  * /v1/rat/reset:
  *   post:
  *     tags: [Rat (SANDBOX)]
- *     summary: Reset a maze so that it can be solved again.
+ *     summary: Reset a maze.
+ *     description: Resets all of the rat's actions for a maze. Allowing for the rat to start from the beginning.
  *     requestBody:
- *       description: Reset request. (Admin may input a userId in the request to reset a specific rat's maze.)
  *       required: true
  *       content:
  *         application/json:
diff --git a/src/controllers/rat-controller/postSmell.ts b/src/controllers/rat-controller/postSmell.ts
@@ -7,7 +7,8 @@ import { asyncHandler, rethrowOrCreateError } from "utils";
  * /v1/rat/smell:
  *   post:
  *     tags: [Rat]
- *     summary: Allows the rat to smell the cheese in the maze.
+ *     summary: Attempts to smell a cheese.
+ *     description: The distance to the nearest cheese, within the smell radius, will be returned. If there are no cheeses in the maze, the distance will be `null`.
  *     requestBody:
  *       description: Smell request.
  *       required: true
diff --git a/src/controllers/rat-controller/rat-controller.ts b/src/controllers/rat-controller/rat-controller.ts
@@ -25,9 +25,9 @@ import postSmell from "./postSmell";
  * @swagger
  * tags:
  *   - name: Rat
- *     description: Rat management
+ *     description: Endpoints used to control a rat.
  *   - name: Rat (SANDBOX)
- *     description: Rat management for sandbox
+ *     description: Set of utility endpoints for rat management to be used in the sandbox environment.
  */
 export class RatController implements Controller {
   initialize(router: Router): void {
diff --git a/src/controllers/root-controller/getParticipants.ts b/src/controllers/root-controller/getParticipants.ts
@@ -3,7 +3,6 @@ import { UserService } from "services";
 import { asyncHandler, rethrowOrCreateError } from "utils";
 
 /**
- * @swagger
  * /v1/participants:
  *   get:
  *     tags: [General (ADMIN)]
diff --git a/src/controllers/root-controller/getRankings.ts b/src/controllers/root-controller/getRankings.ts
@@ -3,7 +3,6 @@ import { ScoreService } from "services";
 import { asyncHandler, rethrowOrCreateError } from "utils";
 
 /**
- * @swagger
  * /v1/rankings:
  *   get:
  *     tags: [General (ADMIN)]
diff --git a/src/controllers/root-controller/index.ts b/src/controllers/root-controller/index.ts
@@ -13,7 +13,7 @@ let counter: number = 1;
  * components:
  *   responses:
  *     Unauthorized:
- *       description: Unauthorized
+ *       description: Request is unauthorized. Make sure to include your token in the `X-API-KEY` request header.
  *       content:
  *         application/json:
  *           schema:
@@ -23,7 +23,7 @@ let counter: number = 1;
  *             title: "Unauthorized"
  *             detail: "User is not authorized!"
  *     Forbidden:
- *       description: Forbidden
+ *       description: Forbidden. User is not authorized to access this resource.
  *       content:
  *         application/json:
  *           schema:
@@ -49,7 +49,7 @@ let counter: number = 1;
  *                 location: "body"
  *
  *     ServerError:
- *       description: Internal Server Error
+ *       description: Internal Server Error. Contact the administrator if the problem persists.
  *       content:
  *         application/json:
  *           schema:
diff --git a/src/enums/index.ts b/src/enums/index.ts
@@ -4,7 +4,6 @@ export enum Environment {
 }
 
 /**
- * @swagger
  * components:
  *   schemas:
  *     Role:
@@ -57,8 +56,8 @@ export enum Direction {
  *   schemas:
  *     ActionType:
  *       type: string
- *       enum: [MOVE]
- *       example: NORTH
+ *       enum: [MOVE, START, EAT, EXIT, SMELL, GRAB, DROP]
+ *       example: MOVE
  */
 export enum ActionType {
   Move = "MOVE",
