CamSwagger.js

Filename	Percent	Threshold	Total	Covered	Uncovered
src/CamSwagger.js	76.57%	80%	175	134	41

// @ts-check
// SPDX-License-Identifier: Zlib
// SPDX-FileCopyrightText: 2024 CERN (home.cern)

import path from "node:path";
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";
import { cloneDeep, merge } from "@cern/nodash";
import { fileURLToPath } from "node:url";

/**
 * @typedef {import('express').Router} Router
 */

const dirname = path.dirname(fileURLToPath(import.meta.url));

class CamSwagger {

  /**
   * @param {CamExpress.CamSwagger.Options} [options]
   * @param {CamExpress.CamSwagger.Info} [extraDoc]
   */
  constructor(options, extraDoc) {

    // fill api defintion
    const definition = options?.definition ?? {
      info: {
        title: "cam-express",
        version: "1.0.0"
      }
    };

    /** @type {any} */
    this.doc = swaggerJSDoc({
      definition,
      apis: [
        path.join(dirname, "**/**.js"),
        path.join(dirname, "../src/**/**.js")
      ]
    });

    this.extra = extraDoc;
  }

  /**
   * @param {Router} router
   */
  register(router) {
    router.get("/api-docs.json", (req, res) => {
      res.json(this.doc);
    });

    const opts = {
      swaggerOptions: {
        docExpansion: "none",
        displayRequestDuration: true
      }
    };

    router.use("/api-docs",
      swaggerUi.serveFiles(this.doc, opts),
      swaggerUi.setup(this.doc, opts)
    );
  }

  /**
   * @brief generate swagger doc for given group and camera
   * @param {string} groupName
   * @param {CamExpress.CameraInfo} camera
   */
  camera(groupName, camera) {
    const path = `/cameras/${groupName}/${camera.name}`;
    const cameraDoc = cloneDeep(this.doc?.paths?.["/cameras/{group}/{camera}"]);

    if (!cameraDoc) {
      console.warn("Unable to find Swagger camera doc");
      return;
    }

    // remove path parameters to be filled
    cameraDoc["get"].parameters.splice(0, 2);

    // replace summary by camera description
    cameraDoc["get"].summary = camera.description ||
      "no description provided for this camera";


    if (camera.ptz) {
      [ "/ptz", "/ptz/limits" ].forEach(
        (sub) => {
          const template = "/cameras/{group}/{camera}" + sub;
          const doc = cloneDeep(this.doc?.paths?.[template]);
          // remove path parameters to be filled
          doc["get"].parameters.splice(0, 2);
          this.doc.paths[path + sub] = doc;
        });
    }
    if (camera.screenshot) {
      const template = "/cameras/{group}/{camera}/screenshot";
      const doc = cloneDeep(this.doc?.paths?.[template]);
      // remove path parameters to be filled
      doc["get"].parameters.splice(0, 2);
      this.doc.paths[path + "/screenshot"] = doc;
    }

    // replace var path with current cam path
    this.doc.paths[path] = cameraDoc;
  }

  /**
   * Add dynamic doc from cameras config
   * @param {CamExpress.CamService} service
   */
  swag(service) {
    let hasPTZ = false;
    let hasSShot = false;

    Object.entries(service.camConfig ?? {}).forEach(([ groupName, group ]) => {
      group.cameras?.forEach((camera) => {
        this.camera(groupName, camera);

        hasPTZ = hasPTZ || (camera?.ptz ?? false);
        hasSShot = hasSShot || (camera?.screenshot ?? false);
      });
    });
    if (!hasPTZ) {
      /* remove ptz documentation if not needed */
      [ "/ptz", "/ptz/limits" ].forEach(
        (sub) => { delete this.doc.paths["/cameras/{group}/{camera}" + sub]; });
    }
    if (!hasSShot) {
      /* remove ptz documentation if not needed */
      [ "/screenshot" ].forEach(
        (sub) => { delete this.doc.paths["/cameras/{group}/{camera}" + sub]; });
    }

    // Insert additional paths in doc
    merge(this.doc?.paths, this.extra?.paths);
  }
}

export default CamSwagger;

[{"file":"src/CamSwagger.js","line":33,"character":9,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":41,"character":9,"text":"extra","kind":1},{"file":"src/CamSwagger.js","line":49,"character":20,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":60,"character":32,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":61,"character":27,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":72,"character":10,"text":"cameraDoc","kind":1},{"file":"src/CamSwagger.js","line":72,"character":37,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":72,"character":42,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":74,"character":9,"text":"cameraDoc","kind":1},{"file":"src/CamSwagger.js","line":80,"character":4,"text":"cameraDoc","kind":1},{"file":"src/CamSwagger.js","line":80,"character":21,"text":"parameters","kind":1},{"file":"src/CamSwagger.js","line":80,"character":32,"text":"splice","kind":1},{"file":"src/CamSwagger.js","line":83,"character":4,"text":"cameraDoc","kind":1},{"file":"src/CamSwagger.js","line":83,"character":21,"text":"summary","kind":1},{"file":"src/CamSwagger.js","line":91,"character":16,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":91,"character":37,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":91,"character":42,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":93,"character":10,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":93,"character":21,"text":"parameters","kind":1},{"file":"src/CamSwagger.js","line":93,"character":32,"text":"splice","kind":1},{"file":"src/CamSwagger.js","line":94,"character":15,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":94,"character":19,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":94,"character":39,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":99,"character":12,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":99,"character":33,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":99,"character":38,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":101,"character":6,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":101,"character":17,"text":"parameters","kind":1},{"file":"src/CamSwagger.js","line":101,"character":28,"text":"splice","kind":1},{"file":"src/CamSwagger.js","line":102,"character":11,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":102,"character":15,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":102,"character":45,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":106,"character":9,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":106,"character":13,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":106,"character":27,"text":"cameraDoc","kind":1},{"file":"src/CamSwagger.js","line":128,"character":31,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":128,"character":35,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":133,"character":31,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":133,"character":35,"text":"paths","kind":1},{"file":"src/CamSwagger.js","line":137,"character":15,"text":"doc","kind":1},{"file":"src/CamSwagger.js","line":137,"character":20,"text":"paths","kind":1}]

TypeScript coverage report