PIMS-1884 Swagger Rework

express-api/Dockerfile

@@ -16,9 +16,6 @@ COPY . .
 # Install packages. Needed for build process.
 RUN npm i
 
-# Generate swagger-output
-RUN npm run swagger
-
 # Compile to JavaScript build 
 RUN npm run build
 

express-api/package.json

@@ -13,7 +13,6 @@
     "test": "cross-env DOTENV_CONFIG_PATH=../.env jest",
     "test:unit": "npm run test -- --testPathPattern=/tests/unit",
     "test:integration": "npm run test -- --testPathPattern=/tests/integration",
-    "swagger": "node ./src/swagger/swagger.mjs",
     "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli",
     "migration": "sh ./src/typeorm/utilities/helperScripts/migrationScript.sh"
   },
@@ -58,6 +57,7 @@
     "@types/node-cron": "3.0.11",
     "@types/nunjucks": "3.2.6",
     "@types/supertest": "6.0.2",
+    "@types/swagger-jsdoc": "6.0.4",
     "@types/swagger-ui-express": "4.1.6",
     "@typescript-eslint/eslint-plugin": "8.1.0",
     "@typescript-eslint/parser": "8.1.0",
@@ -70,6 +70,7 @@
     "prettier": "3.3.0",
     "supertest": "7.0.0",
     "swagger-autogen": "2.23.7",
+    "swagger-jsdoc": "6.2.8",
     "ts-jest": "29.2.0",
     "tsc-alias": "1.8.8",
     "typescript": "5.5.2"

express-api/src/controllers/administrativeAreas/administrativeAreasController.ts

@@ -15,17 +15,11 @@ import userServices from '@/services/users/usersServices';
  * @returns {Response}        A 200 status with a list of administrative areas.
  */
 export const getAdministrativeAreas = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Administrative Areas - Admin']
-   * #swagger.description = 'Returns a paged list of administrative areas from the datasource.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const ssoUser = req.user;
   const filter = AdministrativeAreaFilterSchema.safeParse(req.query);
   if (filter.success) {
     const adminAreas = await administrativeAreasServices.getAdministrativeAreas(filter.data);
+    // TODO: Do we still need this condition? Few fields are trimmed since moving to view.
     if (!ssoUser.hasRoles([Roles.ADMIN])) {
       const trimmed = AdministrativeAreaPublicResponseSchema.array().parse(adminAreas.data);
       return res.status(200).send({
@@ -35,7 +29,7 @@ export const getAdministrativeAreas = async (req: Request, res: Response) => {
     }
     return res.status(200).send(adminAreas);
   } else {
-    return res.status(400).send('Could not parse filter.');
+    return res.status(400).send(filter.error);
   }
 };
 
@@ -46,13 +40,6 @@ export const getAdministrativeAreas = async (req: Request, res: Response) => {
  * @returns {Response}        A 201 status and response with the added administrative area.
  */
 export const addAdministrativeArea = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Administrative Areas - Admin']
-   * #swagger.description = 'Add a new administrative area to the datasource.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const user = await userServices.getUser((req.user as SSOUser).preferred_username);
   const addBody = { ...req.body, CreatedById: user.Id };
   const response = await administrativeAreasServices.addAdministrativeArea(addBody);
@@ -66,14 +53,6 @@ export const addAdministrativeArea = async (req: Request, res: Response) => {
  * @returns {Response}        A 200 status and the administrative area data.
  */
 export const getAdministrativeAreaById = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Administrative Areas - Admin']
-   * #swagger.description = 'Returns an administrative area that matches the supplied ID.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
-
   const id = Number(req.params.id);
   const adminArea = await administrativeAreasServices.getAdministrativeAreaById(id);
   return res.status(200).send(adminArea);
@@ -86,14 +65,6 @@ export const getAdministrativeAreaById = async (req: Request, res: Response) =>
  * @returns {Response}        A 200 status and the administrative area data.
  */
 export const updateAdministrativeAreaById = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Administrative Areas - Admin']
-   * #swagger.description = 'Updates an administrative area that matches the supplied ID.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
-
   const id = req.params.id;
   if (id != req.body.Id) {
     return res.status(400).send('Id mismatched or invalid.');

express-api/src/controllers/agencies/agenciesController.ts

@@ -14,13 +14,6 @@ import { Agency } from '@/typeorm/Entities/Agency';
  * @returns {Response}        A 200 status with a list of agencies.
  */
 export const getAgencies = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Agencies - Admin']
-   * #swagger.description = 'Gets a paged list of agencies.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const ssoUser = req.user;
   const filter = AgencyFilterSchema.safeParse(req.query);
   if (filter.success) {
@@ -45,14 +38,6 @@ export const getAgencies = async (req: Request, res: Response) => {
  * @returns {Response}        A 201 status and the data of the agency added.
  */
 export const addAgency = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Agencies - Admin']
-   * #swagger.description = 'Adds a new agency to the datasource.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
-
   const user = await userServices.getUser((req.user as SSOUser).preferred_username);
   const agency = await agencyService.addAgency({ ...req.body, CreatedById: user.Id });
 
@@ -66,14 +51,6 @@ export const addAgency = async (req: Request, res: Response) => {
  * @returns {Response}        A 200 status and the agency data.
  */
 export const getAgencyById = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Agencies - Admin']
-   * #swagger.description = 'Returns an agency that matches the supplied ID.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
-
   const agency = await agencyService.getAgencyById(parseInt(req.params.id));
   if (!agency) {
     return res.status(404).send('Agency does not exist.');
@@ -88,13 +65,6 @@ export const getAgencyById = async (req: Request, res: Response) => {
  * @returns {Response}        A 200 status and the agency data.
  */
 export const updateAgencyById = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Agencies - Admin']
-   * #swagger.description = 'Updates an agency that matches the supplied ID.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const idParse = z.string().safeParse(req.params.id);
   if (!idParse.success) {
     return res.status(400).send(idParse);
@@ -119,13 +89,6 @@ export const updateAgencyById = async (req: Request, res: Response) => {
  * @returns {Response}        A 204 status indicating successful deletion.
  */
 export const deleteAgencyById = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Agencies - Admin']
-   * #swagger.description = 'Deletes an agency that matches the supplied ID.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const idParse = z.string().safeParse(req.params.id);
   if (!idParse.success) {
     return res.status(400).send(idParse);

express-api/src/controllers/buildings/buildingsController.ts

@@ -41,13 +41,6 @@ export const getBuildings = async (req: Request, res: Response) => {
  * @returns {Response}      A 200 status with a response body containing building data.
  */
 export const getBuilding = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['building']
-   * #swagger.description = 'Get the building from the data source if the user is permitted.'
-   * #swagger.security = [{
-   * "bearerAuth": []
-   * }]
-   */
   const buildingId = Number(req.params.buildingId);
   if (isNaN(buildingId)) {
     return res.status(400).send('Building Id is invalid.');
@@ -73,13 +66,6 @@ export const getBuilding = async (req: Request, res: Response) => {
  * @returns {Response}      A 200 status with a response body containing building data.
  */
 export const updateBuilding = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['building']
-   * #swagger.description = 'Updates the building from the data source if the user is permitted.'
-   * #swagger.security = [{
-   * "bearerAuth": []
-   * }]
-   */
   const buildingId = Number(req.params.buildingId);
   if (isNaN(buildingId) || buildingId !== req.body.Id) {
     return res.status(400).send('Building ID was invalid or mismatched with body.');
@@ -97,13 +83,6 @@ export const updateBuilding = async (req: Request, res: Response) => {
  * @returns {Response}      A 200 status with a response body containing building data.
  */
 export const deleteBuilding = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['building']
-   * #swagger.description = 'Deletes the building from the data source if the user is permitted.'
-   * #swagger.security = [{
-   * "bearerAuth": []
-   * }]
-   */
   const buildingId = Number(req.params.buildingId);
   if (isNaN(buildingId)) {
     return res.status(400).send('Building ID was invalid.');
@@ -123,13 +102,6 @@ export const deleteBuilding = async (req: Request, res: Response) => {
  * Note: the original implementation returns 200, but as a resource is created 201 is better.
  */
 export const addBuilding = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['building']
-   * #swagger.description = 'Creates a new building in the datasource.'
-   * #swagger.security = [{
-   * "bearerAuth": []
-   * }]
-   */
   const user = await userServices.getUser((req.user as SSOUser).preferred_username);
   const createBody: Building = { ...req.body, CreatedById: user.Id };
   createBody.Evaluations = createBody.Evaluations?.map((evaluation) => ({

express-api/src/controllers/healthController.ts

@@ -7,9 +7,5 @@ import { Request, Response } from 'express';
  * @returns {Response}      A 200 status indicating API is healthy and running
  */
 export const healthCheck = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Health']
-   * #swagger.description = 'Returns a 200 (OK) status if API is reached.'
-   */
   return res.status(200).send('/health endpoint reached. API running.');
 };

express-api/src/controllers/lookup/lookupController.ts

@@ -34,13 +34,6 @@ import getConfig from '@/constants/config';
  * @returns {Response}      A 200 status and a list of property classifications.
  */
 export const lookupPropertyClassifications = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Lookup']
-   * #swagger.description = 'Get all property classification entries.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const classifications = await AppDataSource.getRepository(PropertyClassification).find();
   const filtered = classifications.filter((c) => !c.IsDisabled);
   const parsed = ClassificationPublicResponseSchema.array().safeParse(filtered);
@@ -52,13 +45,6 @@ export const lookupPropertyClassifications = async (req: Request, res: Response)
 };
 
 export const lookupBuildingPredominateUse = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Lookup']
-   * #swagger.description = 'Get all predomanite uses entries.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const uses = await AppDataSource.getRepository(BuildingPredominateUse).find();
   const filtered = uses.filter((u) => !u.IsDisabled);
   const parsed = PredominateUsePublicResponseSchema.array().safeParse(filtered);
@@ -70,13 +56,6 @@ export const lookupBuildingPredominateUse = async (req: Request, res: Response)
 };
 
 export const lookupBuildingConstructionType = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['Lookup']
-   * #swagger.description = 'Get all building construction type entries.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const uses = await AppDataSource.getRepository(BuildingConstructionType).find();
   const filtered = uses.filter((u) => !u.IsDisabled);
   const parsed = BuildingConstructionPublicResponseSchema.array().safeParse(filtered);

express-api/src/controllers/ltsa/ltsaController.ts

@@ -8,13 +8,6 @@ import ltsaService from '@/services/ltsa/ltsaServices';
  * @returns {Response}        A 200 status with LTSA order information.
  */
 export const getLTSA = async (req: Request, res: Response) => {
-  /**
-   * #swagger.tags = ['LTSA']
-   * #swagger.description = 'Returns property information from LTSA.'
-   * #swagger.security = [{
-            "bearerAuth": []
-      }]
-   */
   const pid = req.query.pid as string;
   const getLandTitleInfo = await ltsaService.processLTSARequest(pid);
   return res.status(200).send(getLandTitleInfo);

express-api/src/controllers/notifications/notificationsController.ts

@@ -7,6 +7,7 @@ import { Request, Response } from 'express';
 import { DisposalNotificationFilterSchema } from './notificationsSchema';
 import { isAdmin, isAuditor } from '@/utilities/authorizationChecks';
 import projectServices from '@/services/projects/projectsServices';
+import { Roles } from '@/constants/roles';
 import logger from '@/utilities/winstonLogger';
 
 /**
@@ -31,7 +32,9 @@ export const getNotificationsByProjectId = async (req: Request, res: Response) =
 
       const project = await projectServices.getProjectById(filterResult.projectId);
       if (!usersAgencies.includes(project.AgencyId)) {
-        return res.status(403).send({ message: 'User is not authorized to access this endpoint.' });
+        return res
+          .status(403)
+          .send({ message: 'User cannot access project outside their agencies.' });
       }
     }
 
@@ -53,15 +56,14 @@ export const getNotificationsByProjectId = async (req: Request, res: Response) =
 };
 
 export const resendNotificationById = async (req: Request, res: Response) => {
+  const kcUser = req.user;
+  if (!kcUser.hasRoles([Roles.ADMIN]))
+    return res.status(403).send('User lacks permissions to resend notification.');
   const id = Number(req.params.id);
   const notification = await notificationServices.getNotificationById(id);
   if (!notification) {
     return res.status(404).send('Notification not found.');
   }
-  const kcUser = req.user;
-  if (!isAdmin(kcUser)) {
-    return res.status(403).send({ message: 'User is not authorized to access this endpoint.' });
-  }
   const resultantNotification = await notificationServices.sendNotification(notification, kcUser);
   const user = await userServices.getUser(kcUser.preferred_username);
   const updatedNotification = await notificationServices.updateNotificationStatus(
@@ -72,16 +74,19 @@ export const resendNotificationById = async (req: Request, res: Response) => {
 };
 
 export const cancelNotificationById = async (req: Request, res: Response) => {
+  const kcUser = req.user;
+  if (!kcUser.hasRoles([Roles.ADMIN]))
+    return res.status(403).send('User lacks permissions to cancel notification.');
   const id = Number(req.params.id);
   const notification = await notificationServices.getNotificationById(id);
   if (!notification) {
     return res.status(404).send('Notification not found.');
   }
-  const kcUser = req.user;
-  if (!isAdmin(kcUser)) {
-    return res.status(403).send({ message: 'User is not authorized to access this endpoint.' });
-  }
-  const resultantNotification = await notificationServices.cancelNotificationById(notification.Id);
+  const user = await userServices.getUser(kcUser.preferred_username);
+  const resultantNotification = await notificationServices.cancelNotificationById(
+    notification.Id,
+    user,
+  );
   if (resultantNotification.Status !== NotificationStatus.Cancelled) {
     return res.status(400).send(resultantNotification);
   }

express-api/src/controllers/notifications/notificationsSchema.ts

@@ -35,8 +35,8 @@ export const NotificationResponseSchema = z.object({
 });
 
 export const DisposalNotificationFilterSchema = z.object({
-  page: z.number().optional(),
-  quantity: z.number().optional(),
+  page: z.coerce.number().optional(),
+  quantity: z.coerce.number().optional(),
   sort: z.array(z.string()).optional(),
   projectNumber: z.string().optional(),
   projectId: z.coerce.number(),