feat: Swagger Docs

* Import/convert from #892

* docs(swagger): Add swagger definitions for SystemRouter

* Swagger is an optional feature and should be treated as such

* Remove $brand

* docs(swagger): Add swagger definitions for NTPClientRouter

* chore: Fix package-lock

* chore: Fix package-lock

* docs(swagger): Document State Attributes and Map Layer + Map Entities

* Use tagged version

* fix pkg build

* add schema validation

* remove unnecessary custom jsdoc tag

Co-authored-by: Davide Depau <davide@depau.eu>

.github/workflows/manual_build.yml

@@ -18,6 +18,8 @@ jobs:
           node-version: 16.x
       - name: Install
         run: npm ci
+      - name: Generate OpenAPI Docs
+        run: npm run swagger
       - name: Build Valetudo armv7
         run: npm run build --workspace=backend
       - name: Build Valetudo armv7 lowmem

.github/workflows/release.yml

@@ -20,6 +20,8 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Install
         run: npm ci
+      - name: Generate OpenAPI Docs
+        run: npm run swagger
       - name: Build Valetudo armv7
         run: npm run build --workspace=backend
       - name: Build Valetudo armv7 lowmem

.gitignore

@@ -9,3 +9,6 @@ build/
 
 # IntelliJ Idea project files
 .idea/
+
+
+/backend/lib/res/swagger.json

backend/lib/core/capabilities/doc/ManualControlCapability.swagger.json

@@ -0,0 +1,15 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoManualControlMovementCommandType": {
+        "type": "string",
+        "enum": [
+          "forward",
+          "backward",
+          "rotate_clockwise",
+          "rotate_counterclockwise"
+        ]
+      }
+    }
+  }
+}

backend/lib/entities/ContainerEntity.js

@@ -269,6 +269,14 @@ class ContainerEntity extends SerializableEntity {
             this.notifySubscribers(EVENT_TYPE.CHANGE, newAttribute);
         }
     }
+
+    toJSON() {
+        return {
+            __class: this.__class,
+            metaData: this.metaData,
+            attributes: this.attributes
+        };
+    }
 }
 
 module.exports = ContainerEntity;

backend/lib/entities/core/doc/ValetudoDNDConfiguration.swagger.json

@@ -0,0 +1,23 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoDNDConfiguration": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "start": {
+            "$ref": "#/components/schemas/ScheduleTimeDTO"
+          },
+          "end": {
+            "$ref": "#/components/schemas/ScheduleTimeDTO"
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoGoToLocation.swagger.json

@@ -0,0 +1,23 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoGoToLocation": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "coordinates": {
+            "$ref": "#/components/schemas/CoordinateDTO"
+          },
+          "id": {
+            "type": "string"
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoMapSegment.swagger.json

@@ -0,0 +1,20 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoMapSegment": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoMapSnapshot.swagger.json

@@ -0,0 +1,24 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoMapSnapshot": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "timestamp": {
+            "type": "string",
+            "description": "Datetime in ISO8601 format"
+          },
+          "map": {
+            "$ref": "#/components/schemas/ValetudoMap"
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoRestrictedZone.swagger.json

@@ -0,0 +1,35 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoRestrictedZone": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "regular",
+              "mop"
+            ]
+          },
+          "points": {
+            "type": "object",
+            "properties": {
+              "pA": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pB": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pC": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pD": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoSensor.swagger.json

@@ -0,0 +1,29 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoSensor": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "all",
+              "accelerometer",
+              "gyroscope",
+              "bumper",
+              "cliff",
+              "lidar"
+            ]
+          },
+          "subType": {
+            "type": "string"
+          },
+          "value": {},
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoVirtualRestrictions.swagger.json

@@ -0,0 +1,23 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoVirtualRestrictions": {
+        "type": "object",
+        "properties": {
+          "virtualWalls": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ValetudoVirtualWall"
+            }
+          },
+          "restrictedZones": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ValetudoRestrictedZone"
+            }
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoVirtualWall.swagger.json

@@ -0,0 +1,22 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoVirtualWall": {
+        "type": "object",
+        "properties": {
+          "points": {
+            "type": "object",
+            "properties": {
+              "pA": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pB": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoVoicePackOperationStatus.swagger.json

@@ -0,0 +1,27 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoVoicePackOperationStatus": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "idle",
+              "downloading",
+              "installing",
+              "error"
+            ]
+          },
+          "progress": {
+            "type": "number",
+            "description": "Percentage"
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoWifiConfiguration.swagger.json

@@ -0,0 +1,66 @@
+{
+  "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"
+          }
+        }
+      }
+    }
+  }
+}

backend/lib/entities/core/doc/ValetudoZone.swagger.json

@@ -0,0 +1,34 @@
+{
+  "components": {
+    "schemas": {
+      "ValetudoZone": {
+        "type": "object",
+        "properties": {
+          "iterations": {
+            "type": "number"
+          },
+          "points": {
+            "type": "object",
+            "properties": {
+              "pA": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pB": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pC": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              },
+              "pD": {
+                "$ref": "#/components/schemas/CoordinateDTO"
+              }
+            }
+          },
+          "metaData": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}