Merge pull request #684 from csamuele/672-document-api

672 document api

packages/backend/package.json

@@ -7,12 +7,13 @@
     "test": "jest --forceExit --detectOpenHandles",
     "start": "npm run build && node ./build/src/index.js",
     "dev": "tsx watch ./src",
-    "build": "tsc --project ./",
+    "build": "npm run generate:openapi && tsc --project ./",
     "clean": "npx rimraf build node_modules ../node_modules",
     "migrate:latest": "node ./build/src/Migrators/migrate-to-latest.js",
     "migrate:up": "node ./build/src/Migrators/migrate-up.js",
     "migrate:down": "node ./build/src/Migrators/migrate-down.js",
-    "db_sandbox": "npm run-script build && node ./build/src/test/database_sandbox.js"
+    "db_sandbox": "npm run-script build && node ./build/src/test/database_sandbox.js",
+    "generate:openapi": "ts-node ./src/OpenApi/generateSwaggerJSON.ts"
   },
   "keywords": [],
   "author": "",
@@ -27,7 +28,7 @@
     "@types/express": "^4.17.13",
     "@types/jest": "^27.4.1",
     "@types/luxon": "^3.3.0",
-    "@types/node": "^16.11.26",
+    "@types/node": "^16.18.108",
     "@types/pg": "^8.10.2",
     "@types/socket.io": "^3.0.2",
     "axios": "^1.6.8",
@@ -47,10 +48,14 @@
     "pg-format": "^1.0.4",
     "qs": "^6.10.3",
     "seedrandom": "^3.0.5",
-    "socket.io": "^4.7.5"
+    "socket.io": "^4.7.5",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "@types/supertest": "^2.0.12",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.6",
     "jest": "^29.7.0",
     "rimraf": "^5.0.5",
     "supertest": "^6.2.2",

packages/backend/src/Controllers/ballots.controllers.ts → packages/backend/src/Controllers/Ballot/ballots.controllers.ts

@@ -1,8 +1,8 @@
 import { Ballot as BallotType, ballotValidation } from '@equal-vote/star-vote-shared/domain_model/Ballot';
-import { reqIdSuffix } from "../IRequest";
-import Logger from "../Services/Logging/Logger";
-import ServiceLocator from "../ServiceLocator";
-import { responseErr } from '../Util';
+import { reqIdSuffix } from "../../IRequest";
+import Logger from "../../Services/Logging/Logger";
+import ServiceLocator from "../../ServiceLocator";
+import { responseErr } from '../../Util';
 
 var BallotModel =  ServiceLocator.ballotsDb();
 const className = 'Ballots.Controllers';
@@ -25,6 +25,6 @@ const ballotByID = async (req: any, res: any, next: any) => {
 }
 
 
-module.exports = {
+export {
     ballotByID
 }

packages/backend/src/Controllers/castVoteController.ts → packages/backend/src/Controllers/Ballot/castVoteController.ts

@@ -1,19 +1,19 @@
 import { Election, electionValidation } from "@equal-vote/star-vote-shared/domain_model/Election";
 import { ElectionRoll, ElectionRollState } from "@equal-vote/star-vote-shared/domain_model/ElectionRoll";
 import { Ballot, Ballot as BallotType, ballotValidation } from '@equal-vote/star-vote-shared/domain_model/Ballot';
-import { IRequest } from "../IRequest";
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import { IRequest } from "../../IRequest";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { BadRequest, InternalServerError, Unauthorized } from "@curveball/http-errors";
-import { ILoggingContext } from "../Services/Logging/ILogger";
+import { ILoggingContext } from "../../Services/Logging/ILogger";
 import { randomUUID } from "crypto";
 import { Uid } from "@equal-vote/star-vote-shared/domain_model/Uid";
-import { Receipt } from "../Services/Email/EmailTemplates"
-import { getOrCreateElectionRoll, checkForMissingAuthenticationData, getVoterAuthorization } from "./voterRollUtils"
-const { innerGetGlobalElectionStats} = require('./getElectionsController')
-import { IElectionRequest } from "../IRequest";
+import { Receipt } from "../../Services/Email/EmailTemplates"
+import { getOrCreateElectionRoll, checkForMissingAuthenticationData, getVoterAuthorization } from "../Roll/voterRollUtils"
+import { innerGetGlobalElectionStats } from "../Election";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
-import { io } from "../socketHandler";
+import { io } from "../../socketHandler";
 import { Server } from "socket.io";
 
 const ElectionsModel = ServiceLocator.electionsDb();
@@ -117,7 +117,7 @@ async function castVoteController(req: IElectionRequest, res: Response, next: Ne
     await (await EventQueue).publish(castVoteEventQueue, event);
 
     if(io != null){ // necessary for tests
-        (io as Server).to('landing_page').emit('updated_stats', await innerGetGlobalElectionStats());
+        (io as Server).to('landing_page').emit('updated_stats', await innerGetGlobalElectionStats(req));
     }
 
     res.status(200).json({ ballot: inputBallot} );
@@ -159,7 +159,7 @@ function assertVoterMayVote(voterAuthorization:any, ctx:ILoggingContext ): void{
     Logger.debug(ctx, "Voter authorized");
 }
 
-module.exports = {
+export {
     castVoteController,
     handleCastVoteEvent
 }

packages/backend/src/Controllers/deleteAllBallotsForElectionIDController.ts → packages/backend/src/Controllers/Ballot/deleteAllBallotsForElectionIDController.ts

@@ -1,9 +1,9 @@
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { BadRequest } from "@curveball/http-errors";
-import { expectPermission } from "./controllerUtils";
+import { expectPermission } from "../controllerUtils";
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 const BallotModel = ServiceLocator.ballotsDb();
@@ -34,7 +34,7 @@ const deleteAllBallotsForElectionID = async (req: IElectionRequest, res: Respons
     res.json({ success: innerDeleteAllBallotsForElectionID(req) })
 }
 
-module.exports = {
+export {
     deleteAllBallotsForElectionID,
     innerDeleteAllBallotsForElectionID
 }

packages/backend/src/Controllers/getAnonymizedBallotsByElectionIDController.ts → packages/backend/src/Controllers/Ballot/getAnonymizedBallotsByElectionIDController.ts

@@ -1,16 +1,16 @@
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { BadRequest } from "@curveball/http-errors";
-import { expectPermission } from "./controllerUtils";
+import { expectPermission } from "../controllerUtils";
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 import { AnonymizedBallot } from "@equal-vote/star-vote-shared/domain_model/Ballot";
 
 
 const BallotModel = ServiceLocator.ballotsDb();
 
-const getAnonymizedBallotsByElectionID = async (req: IElectionRequest, res: Response, next: NextFunction) => {
+export const getAnonymizedBallotsByElectionID = async (req: IElectionRequest, res: Response, next: NextFunction) => {
     var electionId = req.election.election_id;
     Logger.debug(req, "getBallotsByElectionID: " + electionId);
     const election = req.election;
@@ -34,6 +34,3 @@ const getAnonymizedBallotsByElectionID = async (req: IElectionRequest, res: Resp
     res.json({ ballots: anonymizedBallots })
 }
 
-module.exports = {
-    getAnonymizedBallotsByElectionID
-}

packages/backend/src/Controllers/getBallotByBallotID.ts → packages/backend/src/Controllers/Ballot/getBallotByBallotIDController.ts

@@ -1,7 +1,7 @@
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { BadRequest } from "@curveball/http-errors";
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 const BallotModel = ServiceLocator.ballotsDb();
@@ -27,6 +27,6 @@ const getBallotByBallotID = async (req: IElectionRequest, res: Response, next: N
     res.json({ ballot: ballot })
 }
 
-module.exports = {
+export {
     getBallotByBallotID
 }

packages/backend/src/Controllers/getBallotsByElectionIDController.ts → packages/backend/src/Controllers/Ballot/getBallotsByElectionIDController.ts

@@ -1,9 +1,9 @@
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { BadRequest } from "@curveball/http-errors";
-import { expectPermission } from "./controllerUtils";
+import { expectPermission } from "../controllerUtils";
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 const BallotModel = ServiceLocator.ballotsDb();
@@ -24,6 +24,6 @@ const getBallotsByElectionID = async (req: IElectionRequest, res: Response, next
     res.json({ election: req.election, ballots: ballots })
 }
 
-module.exports = {
+export {
     getBallotsByElectionID
 }

packages/backend/src/Controllers/Ballot/index.ts

@@ -0,0 +1,6 @@
+export * from './ballots.controllers';
+export * from './castVoteController';
+export * from './deleteAllBallotsForElectionIDController';
+export * from './getBallotByBallotIDController';
+export * from './getBallotsByElectionIDController';
+export * from './getAnonymizedBallotsByElectionIDController';

packages/backend/src/Controllers/archiveElectionController.ts → packages/backend/src/Controllers/Election/archiveElectionController.ts

@@ -1,10 +1,10 @@
-import ServiceLocator from '../ServiceLocator';
-import Logger from '../Services/Logging/Logger';
+import ServiceLocator from '../../ServiceLocator';
+import Logger from '../../Services/Logging/Logger';
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { expectPermission } from "./controllerUtils";
+import { expectPermission } from "../controllerUtils";
 import { BadRequest, InternalServerError } from "@curveball/http-errors";
 import { Election } from '@equal-vote/star-vote-shared/domain_model/Election';
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 var ElectionsModel = ServiceLocator.electionsDb();
@@ -31,9 +31,9 @@ const archiveElection = async (req: IElectionRequest, res: Response, next: NextF
         throw new BadRequest(failMsg)
     }
 
-    return res.json({ election: updatedElection })
+    res.json({ election: updatedElection })
 }
 
-module.exports = {
+export {
     archiveElection,
 }

packages/backend/src/Controllers/createElectionController.ts → packages/backend/src/Controllers/Election/createElectionController.ts

@@ -1,11 +1,11 @@
 import { Election, electionValidation } from "@equal-vote/star-vote-shared/domain_model/Election";
 import { ElectionRoll, ElectionRollState } from "@equal-vote/star-vote-shared/domain_model/ElectionRoll";
-import { IRequest } from "../IRequest";
-import ServiceLocator from "../ServiceLocator";
-import Logger from "../Services/Logging/Logger";
+import { IRequest } from "../../IRequest";
+import ServiceLocator from "../../ServiceLocator";
+import Logger from "../../Services/Logging/Logger";
 import { InternalServerError } from "@curveball/http-errors";
-import { ILoggingContext } from "../Services/Logging/ILogger";
-import { expectValidElectionFromRequest, catchAndRespondError, expectPermission } from "./controllerUtils";
+import { ILoggingContext } from "../../Services/Logging/ILogger";
+import { expectValidElectionFromRequest, catchAndRespondError, expectPermission } from "../controllerUtils";
 import { Response, NextFunction } from "express";
 
 var ElectionsModel = ServiceLocator.electionsDb();
@@ -38,6 +38,6 @@ const createAndCheckElection = async (
     return newElection;
 };
 
-module.exports = {
+export {
     createElectionController
 }

packages/backend/src/Controllers/deleteElectionController.ts → packages/backend/src/Controllers/Election/deleteElectionController.ts

@@ -1,11 +1,11 @@
-import ServiceLocator from '../ServiceLocator';
-import Logger from '../Services/Logging/Logger';
-import { responseErr } from '../Util';
-import { IRequest } from '../IRequest';
+import ServiceLocator from '../../ServiceLocator';
+import Logger from '../../Services/Logging/Logger';
+import { responseErr } from '../../Util';
+import { IRequest } from '../../IRequest';
 import { hasPermission, permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { expectPermission } from "./controllerUtils";
+import { expectPermission } from "../controllerUtils";
 import { BadRequest } from "@curveball/http-errors";
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 var ElectionsModel = ServiceLocator.electionsDb();
@@ -23,9 +23,9 @@ const deleteElection = async (req: IElectionRequest, res: Response, next: NextFu
         throw new BadRequest(msg)
     }
     Logger.info(req, `Deleted election ${electionId}`);
-    return res.status(200)
+    res.status(200).send('Election Deleted');
 
 }
-module.exports = {
+export  {
     deleteElection
 }

packages/backend/src/Controllers/editElectionController.ts → packages/backend/src/Controllers/Election/editElectionController.ts

@@ -1,11 +1,11 @@
 import { electionValidation } from '@equal-vote/star-vote-shared/domain_model/Election';
-import ServiceLocator from '../ServiceLocator';
-import Logger from '../Services/Logging/Logger';
-import { responseErr } from '../Util';
-import { expectPermission } from "./controllerUtils";
+import ServiceLocator from '../../ServiceLocator';
+import Logger from '../../Services/Logging/Logger';
+import { responseErr } from '../../Util';
+import { expectPermission } from "../controllerUtils";
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
 import { BadRequest } from "@curveball/http-errors";
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 var ElectionsModel = ServiceLocator.electionsDb();
@@ -44,6 +44,6 @@ const editElection = async (req: IElectionRequest, res: Response, next: NextFunc
     res.json({ election: req.election, voterAuth: { authorized_voter: req.authorized_voter, has_voted: req.has_voted, roles: req.user_auth.roles, permissions: req.user_auth.permissions  } })
 }
 
-module.exports = {
+export  {
     editElection
 }

packages/backend/src/Controllers/editElectionRolesController.ts → packages/backend/src/Controllers/Election/editElectionRolesController.ts

@@ -1,11 +1,11 @@
 import { electionValidation } from '@equal-vote/star-vote-shared/domain_model/Election';
-import ServiceLocator from '../ServiceLocator';
-import Logger from '../Services/Logging/Logger';
-import { responseErr } from '../Util';
-import { expectPermission } from "./controllerUtils";
+import ServiceLocator from '../../ServiceLocator';
+import Logger from '../../Services/Logging/Logger';
+import { responseErr } from '../../Util';
+import { expectPermission } from "../controllerUtils";
 import { permissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
 import { BadRequest } from "@curveball/http-errors";
-import { IElectionRequest } from "../IRequest";
+import { IElectionRequest } from "../../IRequest";
 import { Response, NextFunction } from 'express';
 
 var ElectionsModel = ServiceLocator.electionsDb();
@@ -38,6 +38,6 @@ const editElectionRoles = async (req: IElectionRequest, res: Response, next: Nex
     res.status(200).json({election: req.election})
 }
 
-module.exports = {
+export {
     editElectionRoles
 }

packages/backend/src/Controllers/elections.controllers.ts → packages/backend/src/Controllers/Election/elections.controllers.ts

@@ -1,11 +1,11 @@
 import { Election, removeHiddenFields } from '@equal-vote/star-vote-shared/domain_model/Election';
-import ServiceLocator from '../ServiceLocator';
-import Logger from '../Services/Logging/Logger';
-import { responseErr } from '../Util';
-import { IElectionRequest, IRequest } from '../IRequest';
+import ServiceLocator from '../../ServiceLocator';
+import Logger from '../../Services/Logging/Logger';
+import { responseErr } from '../../Util';
+import { IElectionRequest, IRequest } from '../../IRequest';
 import { roles } from "@equal-vote/star-vote-shared/domain_model/roles"
 import { getPermissions } from '@equal-vote/star-vote-shared/domain_model/permissions';
-import { getOrCreateElectionRoll, checkForMissingAuthenticationData, getVoterAuthorization } from "./voterRollUtils"
+import { getOrCreateElectionRoll, checkForMissingAuthenticationData, getVoterAuthorization } from "../Roll/voterRollUtils"
 import { ElectionRoll } from '@equal-vote/star-vote-shared/domain_model/ElectionRoll';
 
 
@@ -156,7 +156,7 @@ const returnElection = async (req: any, res: any, next: any) => {
     res.json({ election: election, voterAuth: { authorized_voter: voterAuthorization.authorized_voter, has_voted: voterAuthorization.has_voted, required: voterAuthorization.required, roles: req.user_auth.roles, permissions: req.user_auth.permissions } })
 }
 
-module.exports = {
+export  {
     returnElection,
     getElectionByID,
     electionSpecificAuth,