Swagger for location routes

Author: Calvicii

src/index.ts

@@ -79,7 +79,7 @@ app.get("/api/status", async (req, res) => {
 // Swagger
 const swaggerOptions: Options = {
   definition: {
-    openapi: "3.1.0",
+    openapi: "3.0.0",
     info: {
       title: "Onloc API",
       version: "1.1.0",

src/openapi/schemas.yaml

@@ -4,8 +4,7 @@ components:
       type: object
       properties:
         id:
-          type: integer
-          format: int64
+          type: string
         username:
           type: string
         admin:
@@ -59,9 +58,7 @@ components:
       type: object
       properties:
         id:
-          type: integer
-          format: int64
-          description: API key ID
+          type: string
         name:
           type: string
         key:
@@ -80,37 +77,13 @@ components:
         - created_at
         - updated_at
 
-    ApiKeyList:
-      type: array
-      items:
-        type: object
-        properties:
-          id:
-            type: integer
-            format: int64
-          name:
-            type: string
-          created_at:
-            type: string
-            format: date-time
-          updated_at:
-            type: string
-            format: date-time
-        required:
-          - id
-          - name
-          - created_at
-          - updated_at
-
     DeviceSafe:
       type: object
       properties:
         id:
-          type: integer
-          format: int64
+          type: string
         user_id:
-          type: integer
-          format: int64
+          type: string
         name:
           type: string
         icon:
@@ -136,28 +109,125 @@ components:
       type: object
       properties:
         id:
-          type: integer
-          format: int64
+          type: string
         device_id:
-          type: integer
-          format: int64
+          type: string
         latitude:
           type: number
         longitude:
           type: number
         accuracy:
           type: number
           nullable: true
+        altitude:
+          type: number
+          nullable: true
+        altitude_accuracy:
+          type: number
+          nullable: true
+        battery:
+          type: integer
+          nullable: true
+          description: Battery percentage (1-100)
         created_at:
           type: string
           format: date-time
+        updated_at:
+          type: string
+          format: date-time
       required:
         - id
         - device_id
         - latitude
         - longitude
         - created_at
 
+    # Reusable request bodies for locations
+    LocationCreate:
+      type: object
+      description: Payload to create a new location for a device
+      required:
+        - device_id
+        - latitude
+        - longitude
+      properties:
+        device_id:
+          type: string
+          description: Device ID this location belongs to
+          example: "123"
+        latitude:
+          type: number
+          format: float
+          example: 51.5074
+        longitude:
+          type: number
+          format: float
+          example: -0.1278
+        accuracy:
+          type: number
+          nullable: true
+          description: Accuracy in meters
+        altitude:
+          type: number
+          nullable: true
+          description: Altitude in meters
+        altitude_accuracy:
+          type: number
+          nullable: true
+        battery:
+          type: integer
+          nullable: true
+          description: Battery percentage (1-100)
+      example:
+        device_id: "123"
+        latitude: 51.5074
+        longitude: -0.1278
+        accuracy: 5.2
+        altitude: 15.0
+        altitude_accuracy: 1.0
+        battery: 78
+
+    LocationUpdate:
+      type: object
+      description: Payload to update an existing location
+      required:
+        - id
+      properties:
+        id:
+          type: string
+          description: Location ID to update
+          example: "456"
+        device_id:
+          type: string
+          description: Device ID this location belongs to (optional)
+        latitude:
+          type: number
+          format: float
+        longitude:
+          type: number
+          format: float
+        accuracy:
+          type: number
+          nullable: true
+        altitude:
+          type: number
+          nullable: true
+        altitude_accuracy:
+          type: number
+          nullable: true
+        battery:
+          type: integer
+          nullable: true
+      example:
+        id: "123"
+        device_id: "456"
+        latitude: 51.5074
+        longitude: -0.1278
+        accuracy: 5.2
+        altitude: 15.0
+        altitude_accuracy: 1.0
+        battery: 78
+
     DeviceWithExtras:
       allOf:
         - $ref: "#/components/schemas/DeviceSafe"

src/routes/apiKeyRoutes.ts

@@ -62,7 +62,7 @@ router.post("/", createApiKey)
  * /api/apikeys:
  *   get:
  *     summary: List all API keys for the current user
- *     description: Returns all API keys belonging to the authenticated user. The actual key value is never returned in this endpoint for security.
+ *     description: Returns all API keys belonging to the authenticated user.
  *     tags: [API Keys]
  *     security:
  *       - bearerAuth: []
@@ -75,7 +75,9 @@ router.post("/", createApiKey)
  *               type: object
  *               properties:
  *                 api_keys:
- *                   $ref: "#/components/schemas/ApiKeyList"
+ *                   type: array
+ *                   items:
+ *                     $ref: "#/components/schemas/ApiKeySafe"
  *       401:
  *         $ref: "#/components/responses/Unauthorized"
  *       500:
@@ -96,11 +98,10 @@ router.get("/", readApiKeys)
  *       - in: path
  *         name: id
  *         schema:
- *           type: integer
- *           format: int64
+ *           type: string
  *         required: true
  *         description: The API key ID to delete
- *         example: 123
+ *         example: "123"
  *     responses:
  *       204:
  *         description: API key deleted successfully (no content)

src/routes/deviceRoutes.ts

@@ -101,9 +101,9 @@ router.get("/", readDevices)
  *         in: path
  *         required: true
  *         schema:
- *           type: integer
- *           format: int64
+ *           type: string
  *         description: Device ID
+ *         example: "123"
  *     responses:
  *       200:
  *         description: Device details
@@ -145,8 +145,7 @@ router.get("/:id", readDevice)
  *             required: [id]
  *             properties:
  *               id:
- *                 type: integer
- *                 format: int64
+ *                 type: string
  *               name:
  *                 type: string
  *               icon:
@@ -187,9 +186,9 @@ router.patch("/", updateDevice)
  *         in: path
  *         required: true
  *         schema:
- *           type: integer
- *           format: int64
+ *           type: string
  *         description: Device ID to delete
+ *         example: "123"
  *     responses:
  *       204:
  *         description: Device deleted successfully (no content)
@@ -219,9 +218,9 @@ router.delete("/:id", deleteDevice)
  *         in: path
  *         required: true
  *         schema:
- *           type: integer
- *           format: int64
+ *           type: string
  *         description: Device ID
+ *         example: "123"
  *     responses:
  *       200:
  *         description: Ring command sent (device online)