added swagger docs

src/features/api/features/settings/settings.ts

@@ -9,16 +9,78 @@ import {
 import { BrowserWindow } from "electron";
 import { globalEvents } from "../../../../constants/globalEvents";
 
+/**
+ * @swagger
+ * tags:
+ *   name: settings
+ *   description: The settings management API
+ * components:
+ *   schemas:
+ *     StringArray:
+ *       type: array
+ *       items:
+ *         type: string
+ *       example: ["Artist1", "Artist2"]
+ *
+ * @param expressApp
+ * @param mainWindow
+ */
 export const addSettingsAPI = (expressApp: Router, mainWindow: BrowserWindow) => {
+  /**
+   * @swagger
+   * /settings/skipped-artists:
+   *   get:
+   *     summary: get a list of artists that TIDAL Hi-Fi will skip if skipping is enabled
+   *     tags: [settings]
+   *     responses:
+   *       200:
+   *         description: The list book.
+   *         content:
+   *           application/json:
+   *             schema:
+   *              $ref: '#/components/schemas/StringArray'
+   */
   expressApp.get("/settings/skipped-artists", (req, res) => {
     res.json(settingsStore.get<string, string[]>(settings.skippedArtists));
   });
 
+  /**
+   * @swagger
+   * /settings/skipped-artists:
+   *   post:
+   *     summary: Add new artists to the list of skipped artists
+   *     tags: [settings]
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/StringArray'
+   *     responses:
+   *       200:
+   *         description: Ok
+   */
   expressApp.post("/settings/skipped-artists", (req: Request<object, object, string[]>, res) => {
     addSkippedArtists(req.body);
     res.sendStatus(200);
   });
 
+  /**
+   * @swagger
+   * /settings/skipped-artists/delete:
+   *   post:
+   *     summary: Remove artists from the list of skipped artists
+   *     tags: [settings]
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/StringArray'
+   *     responses:
+   *       200:
+   *         description: Ok
+   */
   expressApp.post(
     "/settings/skipped-artists/delete",
     (req: Request<object, object, string[]>, res) => {
@@ -27,11 +89,31 @@ export const addSettingsAPI = (expressApp: Router, mainWindow: BrowserWindow) =>
     }
   );
 
+  /**
+   * @swagger
+   * /settings/skipped-artists/current:
+   *   post:
+   *     summary: Add the current artist to the list of skipped artists
+   *     tags: [settings]
+   *     responses:
+   *       200:
+   *        description: Ok
+   */
   expressApp.post("/settings/skipped-artists/current", (req, res) => {
     addSkippedArtists([mediaInfo.artists]);
     mainWindow.webContents.send("globalEvent", globalEvents.next);
     res.sendStatus(200);
   });
+  /**
+   * @swagger
+   * /settings/skipped-artists/current:
+   *   delete:
+   *     summary: Remove the current artist from the list of skipped artists
+   *     tags: [settings]
+   *     responses:
+   *       200:
+   *        description: Ok
+   */
   expressApp.delete("/settings/skipped-artists/current", (req, res) => {
     removeSkippedArtists([mediaInfo.artists]);
     res.sendStatus(200);

src/features/api/index.ts

@@ -1,7 +1,9 @@
 import { BrowserWindow, dialog } from "electron";
 import express from "express";
-import { settings } from "../../constants/settings";
+import swaggerjsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
 import { settingsStore } from "../../scripts/settings";
+import { settings } from "./../../constants/settings";
 import { addCurrentInfo } from "./features/current";
 import { addPlaybackControl } from "./features/player";
 import { addSettingsAPI } from "./features/settings/settings";
@@ -11,9 +13,41 @@ import { addLegacyApi } from "./legacy";
  * Function to enable TIDAL Hi-Fi's express api
  */
 export const startApi = (mainWindow: BrowserWindow) => {
+  const port = settingsStore.get<string, number>(settings.apiSettings.port);
+  const specs = swaggerjsdoc({
+    definition: {
+      openapi: "3.1.0",
+      info: {
+        title: "TIDAL Hi-Fi API",
+        version: "5.12.0",
+        description: "",
+        license: {
+          name: "MIT",
+          url: "https://github.com/Mastermindzh/tidal-hifi/blob/master/LICENSE",
+        },
+        contact: {
+          name: "Rick <mastermindzh> van Lieshout",
+          url: "https://www.rickvanlieshout.com",
+        },
+      },
+      servers: [
+        {
+          url: `http://localhost:${port}`,
+        },
+      ],
+      externalDocs: {
+        description: "swagger.json",
+        url: "swagger.json",
+      },
+    },
+    apis: ["**/*.ts"],
+  });
+
   const expressApp = express();
   expressApp.use(express.json());
+  expressApp.use("/docs", swaggerUi.serve, swaggerUi.setup(specs));
   expressApp.get("/", (req, res) => res.send("Hello World!"));
+  expressApp.get("/swagger.json", (req, res) => res.json(specs));
 
   // add features
   addLegacyApi(expressApp, mainWindow);
@@ -21,7 +55,6 @@ export const startApi = (mainWindow: BrowserWindow) => {
   addCurrentInfo(expressApp);
   addSettingsAPI(expressApp, mainWindow);
 
-  const port = settingsStore.get<string, number>(settings.apiSettings.port);
   const expressInstance = expressApp.listen(port, "127.0.0.1");
   expressInstance.on("error", function (e: { code: string }) {
     let message = e.code;