Add Swagger API documentation

apps/server/package.json

@@ -11,15 +11,18 @@
     "cors": "2.8.5",
     "dotenv": "^16.0.1",
     "express": "5.1.0",
+    "express-openapi-validator": "^5.6.0",
     "express-static-gzip": "3.0.0",
     "express-validator": "7.2.1",
-    "multer": "2.0.1",
     "fast-equals": "^5.0.1",
     "google-auth-library": "^9.4.2",
     "lowdb": "^7.0.1",
+    "multer": "2.0.1",
     "ontime-utils": "workspace:*",
     "osc-min": "2.1.2",
     "sanitize-filename": "^1.6.3",
+    "swagger-jsdoc": "6.2.8",
+    "swagger-ui-express": "5.0.0",
     "ws": "^8.18.0",
     "xlsx": "^0.18.5"
   },
@@ -29,6 +32,8 @@
     "@types/express": "5.0.3",
     "@types/multer": "1.4.13",
     "@types/node": "catalog:",
+    "@types/swagger-jsdoc": "6.0.4",
+    "@types/swagger-ui-express": "4.1.6",
     "@types/websocket": "^1.0.5",
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "catalog:",
@@ -48,17 +53,13 @@
   "scripts": {
     "addversion": "node -p \"'export const ONTIME_VERSION = ' + JSON.stringify(require('../../package.json').version) + ';'\" > src/ONTIME_VERSION.js",
     "postinstall": "pnpm addversion",
-
     "dev": "cross-env NODE_ENV=development tsx watch ./src/index.ts",
     "dev:electron": "pnpm dev",
     "dev:inspect": "cross-env NODE_ENV=development tsx watch --inspect ./src/index.ts",
-
     "lint": "eslint . --quiet",
     "typecheck": "tsc --noEmit",
-
     "prebuild": "tsx ./scripts/bundleCss.ts && tsx ./scripts/bundleTranslation.ts",
     "build": "node esbuild.js",
-
     "test": "cross-env IS_TEST=true vitest",
     "test:inspect": "cross-env IS_TEST=true vitest --inspect --no-file-parallelism",
     "test:pipeline": "cross-env IS_TEST=true vitest run"

apps/server/src/api-data/automation/automation.router.ts

@@ -23,15 +23,110 @@ import { paramsWithId } from '../validation-utils/validationFunction.js';
 
 export const router = express.Router();
 
+/**
+ * @swagger
+ * /data/automations:
+ *   get:
+ *     summary: Get automation settings
+ *     responses:
+ *       200:
+ *         description: The automation settings
+ *   post:
+ *     summary: Update automation settings
+ *     responses:
+ *       204:
+ *         description: Successfully updated
+ */
 router.get('/', getAutomationSettings);
 router.post('/', validateAutomationSettings, postAutomationSettings);
 
+/**
+ * @swagger
+ * /data/automations/trigger:
+ *   post:
+ *     summary: Create a new trigger
+ *     responses:
+ *       201:
+ *         description: Successfully created
+ */
 router.post('/trigger', validateTrigger, postTrigger);
+
+/**
+ * @swagger
+ * /data/automations/trigger/{id}:
+ *   put:
+ *     summary: Update a trigger
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully updated
+ *   delete:
+ *     summary: Delete a trigger
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully deleted
+ */
 router.put('/trigger/:id', validateTriggerPatch, putTrigger);
 router.delete('/trigger/:id', paramsWithId, deleteTrigger);
 
+/**
+ * @swagger
+ * /data/automations/automation:
+ *   post:
+ *     summary: Create a new automation
+ *     responses:
+ *       201:
+ *         description: Successfully created
+ */
 router.post('/automation', validateAutomation, postAutomation);
+
+/**
+ * @swagger
+ * /data/automations/automation/{id}:
+ *   put:
+ *     summary: Update an automation
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully updated
+ *   delete:
+ *     summary: Delete an automation
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully deleted
+ */
 router.put('/automation/:id', validateAutomationPatch, editAutomation);
 router.delete('/automation/:id', paramsWithId, deleteAutomation);
 
+/**
+ * @swagger
+ * /data/automations/test:
+ *   post:
+ *     summary: Test an automation output
+ *     responses:
+ *       200:
+ *         description: Success
+ */
 router.post('/test', validateTestPayload, testOutput);

apps/server/src/api-data/custom-fields/customFields.router.ts

@@ -14,15 +14,42 @@ import { validateCustomField, validateDeleteCustomField, validateEditCustomField
 export const router = express.Router();
 
 /**
- * Gets all the custom fields for the project
+ * @swagger
+ * /data/custom-fields:
+ *   get:
+ *     summary: Get all custom fields for the project
+ *     responses:
+ *       200:
+ *         description: A list of custom fields
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 customFields:
+ *                   type: array
+ *                   items:
+ *                     type: object
  */
 router.get('/', async (_req: Request, res: Response<CustomFields>) => {
   const customFields = getProjectCustomFields();
   res.status(200).json(customFields);
 });
 
 /**
- * Creates a new custom field
+ * @swagger
+ * /data/custom-fields:
+ *   post:
+ *     summary: Create a new custom field
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *     responses:
+ *       201:
+ *         description: The updated list of custom fields
  */
 router.post('/', validateCustomField, async (req: Request, res: Response<CustomFields | ErrorResponse>) => {
   try {
@@ -35,7 +62,25 @@ router.post('/', validateCustomField, async (req: Request, res: Response<CustomF
 });
 
 /**
- * Modifies the properties of an existing custom field
+ * @swagger
+ * /data/custom-fields/{key}:
+ *   put:
+ *     summary: Update a custom field
+ *     parameters:
+ *       - in: path
+ *         name: key
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *     responses:
+ *       200:
+ *         description: The updated list of custom fields
  */
 router.put('/:key', validateEditCustomField, async (req: Request, res: Response<CustomFields | ErrorResponse>) => {
   try {
@@ -52,7 +97,19 @@ router.put('/:key', validateEditCustomField, async (req: Request, res: Response<
 });
 
 /**
- * Deletes an existing custom field
+ * @swagger
+ * /data/custom-fields/{key}:
+ *   delete:
+ *     summary: Delete a custom field
+ *     parameters:
+ *       - in: path
+ *         name: key
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: The updated list of custom fields
  */
 router.delete('/:key', validateDeleteCustomField, async (req: Request, res: Response<CustomFields | ErrorResponse>) => {
   try {

apps/server/src/api-data/db/db.router.ts

@@ -26,18 +26,147 @@ import {
 
 export const router = express.Router();
 
+/**
+ * @swagger
+ * /data/db:
+ *   get:
+ *     summary: Download the current project file
+ *     responses:
+ *       200:
+ *         description: The project file
+ *   patch:
+ *     summary: Patch the current project file
+ *     responses:
+ *       204:
+ *         description: Successfully updated
+ */
 router.get('/', currentProjectDownload);
+router.patch('/', validatePatchProject, patchPartialProjectFile);
+
+/**
+ * @swagger
+ * /data/db/download:
+ *   post:
+ *     summary: Download a project file
+ *     responses:
+ *       200:
+ *         description: The project file
+ */
 router.post('/download', validateFilenameBody, projectDownload);
+
+/**
+ * @swagger
+ * /data/db/upload:
+ *   post:
+ *     summary: Upload a project file
+ *     responses:
+ *       204:
+ *         description: Successfully uploaded
+ */
 router.post('/upload', uploadProjectFile, postProjectFile);
 
-router.patch('/', validatePatchProject, patchPartialProjectFile);
+/**
+ * @swagger
+ * /data/db/new:
+ *   post:
+ *     summary: Create a new project file
+ *     responses:
+ *       201:
+ *         description: Successfully created
+ */
 router.post('/new', validateFilenameBody, validateNewProject, createProjectFile);
+
+/**
+ * @swagger
+ * /data/db/quick:
+ *   post:
+ *     summary: Create a new project file from a rundown
+ *     responses:
+ *       201:
+ *         description: Successfully created
+ */
 router.post('/quick', validateQuickProject, quickProjectFile);
 
+/**
+ * @swagger
+ * /data/db/all:
+ *   get:
+ *     summary: Get a list of all project files
+ *     responses:
+ *       200:
+ *         description: A list of project files
+ */
 router.get('/all', listProjects);
 
+/**
+ * @swagger
+ * /data/db/load:
+ *   post:
+ *     summary: Load a project file
+ *     responses:
+ *       204:
+ *         description: Successfully loaded
+ */
 router.post('/load', validateFilenameBody, loadProject);
+
+/**
+ * @swagger
+ * /data/db/demo:
+ *   post:
+ *     summary: Load the demo project file
+ *     responses:
+ *       204:
+ *         description: Successfully loaded
+ */
 router.post('/demo', loadDemo);
+
+/**
+ * @swagger
+ * /data/db/{filename}/duplicate:
+ *   post:
+ *     summary: Duplicate a project file
+ *     parameters:
+ *       - in: path
+ *         name: filename
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       201:
+ *         description: Successfully duplicated
+ */
 router.post('/:filename/duplicate', validateFilenameParam, validateNewFilenameBody, duplicateProjectFile);
+
+/**
+ * @swagger
+ * /data/db/{filename}/rename:
+ *   put:
+ *     summary: Rename a project file
+ *     parameters:
+ *       - in: path
+ *         name: filename
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully renamed
+ */
 router.put('/:filename/rename', validateFilenameParam, validateNewFilenameBody, renameProjectFile);
+
+/**
+ * @swagger
+ * /data/db/{filename}:
+ *   delete:
+ *     summary: Delete a project file
+ *     parameters:
+ *       - in: path
+ *         name: filename
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       204:
+ *         description: Successfully deleted
+ */
 router.delete('/:filename', validateFilenameParam, deleteProjectFile);