Swagger docs

.eslintrc.json

@@ -79,7 +79,7 @@
         "eol-last": ["error", "always"],
         "jsdoc/check-alignment": "error",
         "jsdoc/check-param-names": "error",
-        "jsdoc/check-tag-names": "error",
+        "jsdoc/check-tag-names": ["error", { "definedTags": ["swagger"] }],
         "jsdoc/check-types": "error",
         "jsdoc/implements-on-classes": "error",
         "jsdoc/newline-after-description": "error",

.gitignore

@@ -14,3 +14,6 @@
 
 # IntelliJ Idea project files
 /.idea/
+
+# Swagger docs
+/lib/res/swagger.json

lib/entities/core/ValetudoWifiConfiguration.js

@@ -1,5 +1,52 @@
 const SerializableEntity = require("../SerializableEntity");
 
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ValetudoWifiConfiguration:
+ *       type: object
+ *       properties:
+ *         ssid:
+ *           type: string
+ *           description: "Wireless network name"
+ *         credentials:
+ *           type: object
+ *           properties:
+ *             type:
+ *               type: string
+ *             typeSpecificSettings:
+ *               type: object
+ *               description: "Settings depending on type, for example WPA preshared key"
+ *         details:
+ *           type: object
+ *           properties:
+ *             state:
+ *               type: string
+ *               enum:
+ *                 - connected
+ *                 - not_connected
+ *                 - unknown
+ *             downspeed:
+ *               type: number
+ *             upspeed:
+ *               type: number
+ *             signal:
+ *               type: number
+ *             ips:
+ *               type: array
+ *               description: "IP addresses"
+ *               items:
+ *                 type: string
+ *             frequency:
+ *               type: string
+ *               enum:
+ *                 - 2.4ghz
+ *                 - 5ghz
+ *         metaData:
+ *           type: object
+ *
+ */
 
 // noinspection JSCheckFunctionSignatures
 class ValetudoWifiConfiguration extends SerializableEntity {

lib/entities/core/ValetudoZone.js

@@ -1,5 +1,28 @@
 const SerializableEntity = require("../SerializableEntity");
 
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ValetudoZone:
+ *       type: object
+ *       properties:
+ *         iterations:
+ *           type: number
+ *         points:
+ *           type: object
+ *           properties:
+ *             pA:
+ *               $ref: "#/components/schemas/SizeDTO"
+ *             pB:
+ *               $ref: "#/components/schemas/SizeDTO"
+ *             pC:
+ *               $ref: "#/components/schemas/SizeDTO"
+ *             pD:
+ *               $ref: "#/components/schemas/SizeDTO"
+ *         metaData:
+ *           type: object
+ */
 
 // noinspection JSCheckFunctionSignatures
 class ValetudoZone extends SerializableEntity {

lib/entities/core/ValetudoZonePreset.js

@@ -1,7 +1,24 @@
 const SerializableEntity = require("../SerializableEntity");
 const uuid = require("uuid");
 
-
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ValetudoZonePreset:
+ *       type: object
+ *       properties:
+ *         name:
+ *           type: string
+ *         id:
+ *           type: string
+ *         metaData:
+ *           type: object
+ *         zones:
+ *           type: array
+ *           items:
+ *             $ref: "#/components/schemas/ValetudoZone"
+ */
 // noinspection JSCheckFunctionSignatures
 class ValetudoZonePreset extends SerializableEntity {
     /**

lib/entities/map/ValetudoMap.js

@@ -11,6 +11,28 @@ const ValetudoMapSegment = require("../core/ValetudoMapSegment");
  * The origin is found on the top-left corner
  *
  */
+// TODO: add Swagger JSON schemas for children
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ValetudoMap:
+ *       type: object
+ *       properties:
+ *         size:
+ *           $ref: "#/components/schemas/SizeDTO"
+ *         pixelSize:
+ *           type: integer
+ *         layers:
+ *           type: array
+ *         entities:
+ *           type: array
+ *         metaData:
+ *           type: object
+ *           properties:
+ *             version:
+ *               type: number
+ */
 class ValetudoMap extends SerializableEntity { //TODO: Current, Historic, Etc.
     /**
      *

lib/webserver/CapabilitiesRouter.js

@@ -23,6 +23,24 @@ class CapabilitiesRouter {
 
 
     initRoutes() {
+        /**
+         * @swagger
+         * /api/v2/robot/capabilities:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot supported capabilities
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: array
+         *               items:
+         *                 type: string
+         *                 description: "Capability class name"
+         */
         this.router.get("/", (req, res) => {
             res.json(Object.values(this.robot.capabilities).map(c => c.getType()));
         });

lib/webserver/RobotRouter.js

@@ -24,6 +24,29 @@ class RobotRouter {
 
 
     initRoutes() {
+        /**
+         * @swagger
+         * /api/v2/robot:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot info
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: object
+         *               properties:
+         *                 manufacturer:
+         *                   type: string
+         *                 modelName:
+         *                   type: string
+         *                 implementation:
+         *                   type: string
+         *                   description: "Valetudo robot implementation in use"
+         */
         this.router.get("/", (req, res) => {
             res.json({
                 manufacturer: this.robot.getManufacturer(),
@@ -32,6 +55,26 @@ class RobotRouter {
             });
         });
 
+        /**
+         * @swagger
+         * /api/v2/robot/state:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot state
+         *     description: |
+         *       Retrieve the robot state.
+         *
+         *       Note! If the map is available, trying this out on Swagger will likely **use lots of RAM and hang your
+         *       browser tab.**
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: object
+         */
         this.router.get("/state", async (req, res) => {
             try {
                 const polledState = await this.robot.pollState();
@@ -42,6 +85,23 @@ class RobotRouter {
             }
         });
 
+
+        // TODO: add Swagger JSON schemas for state attributes
+        /**
+         * @swagger
+         * /api/v2/robot/state/attributes:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot state attributes
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: object
+         */
         this.router.get("/state/attributes", async (req, res) => {
             try {
                 const polledState = await this.robot.pollState();
@@ -52,6 +112,26 @@ class RobotRouter {
             }
         });
 
+        /**
+         * @swagger
+         * /api/v2/robot/state/map:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot map
+         *     description: |
+         *       Retrieve the robot map.
+         *
+         *       Note! If the map is available, trying this out on Swagger will likely **use lots of RAM and hang your
+         *       browser tab.**
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           application/json:
+         *             schema:
+         *               $ref: "#/components/schemas/ValetudoMap"
+         */
         this.router.get("/state/map", async (req, res) => {
             try {
                 const polledState = await this.robot.pollState();
@@ -62,8 +142,6 @@ class RobotRouter {
             }
         });
 
-
-
         this.router.use("/capabilities/", new CapabilitiesRouter({
             robot: this.robot,
             enableDebugCapability: this.enableDebugCapability
@@ -89,6 +167,25 @@ class RobotRouter {
             this.sseHubs.map.event(ValetudoRobot.EVENTS.MapUpdated, this.robot.state.map);
         });
 
+        /**
+         * @swagger
+         * /api/v2/robot/state/sse:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot state (SSE events)
+         *     description: |
+         *       Retrieve the robot state.
+         *
+         *       Note! This endpoint provides SSE events. Swagger does not support it.
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           text/event-stream:
+         *             schema:
+         *               type: object
+         */
         this.router.get(
             "/state/sse",
             sseHub({hub: this.sseHubs.state, flushAfterWrite: true}),
@@ -97,6 +194,25 @@ class RobotRouter {
             }
         );
 
+        /**
+         * @swagger
+         * /api/v2/robot/state/attributes/sse:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot state attributes (SSE events)
+         *     description: |
+         *       Retrieve the robot state attributes.
+         *
+         *       Note! This endpoint provides SSE events. Swagger does not support it.
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           text/event-stream:
+         *             schema:
+         *               type: object
+         */
         this.router.get(
             "/state/attributes/sse",
             sseHub({hub: this.sseHubs.attributes, flushAfterWrite: true}),
@@ -105,6 +221,26 @@ class RobotRouter {
             }
         );
 
+
+        /**
+         * @swagger
+         * /api/v2/robot/state/map/sse:
+         *   get:
+         *     tags:
+         *       - robot
+         *     summary: Get robot map (SSE events)
+         *     description: |
+         *       Retrieve the robot map
+         *
+         *       Note! This endpoint provides SSE events. Swagger does not support it.
+         *     responses:
+         *       200:
+         *         description: Ok
+         *         content:
+         *           text/event-stream:
+         *             schema:
+         *               $ref: "#/components/schemas/ValetudoMap"
+         */
         this.router.get(
             "/state/map/sse",
             sseHub({hub: this.sseHubs.map, flushAfterWrite: true}),