chore: openapi docs for undocumented routes and fix two broken doc blocks

plugins/automations/src/backend/maintenance-routes.ts

@@ -8,6 +8,16 @@ export function registerMaintenanceRoutes(
   ctx: PluginContext,
   service: MaintenanceService,
 ) {
+  /**
+   * @openapi
+   * /plugin-api/automations/maintenance:
+   *   get:
+   *     summary: List maintenance windows on the caller's hosts
+   *     tags: [Automations]
+   *     responses:
+   *       200: { description: Maintenance state per host. }
+   *       401: { description: Not signed in. }
+   */
   router.get(
     "/maintenance",
     ctx.rbac.require("view") as never,
@@ -65,11 +75,57 @@ export function registerMaintenanceRoutes(
       res.status(500).json({ error: "Failed to update maintenance" });
     }
   };
+  /**
+   * @openapi
+   * /plugin-api/automations/maintenance/{hostId}:
+   *   get:
+   *     summary: Get a host's maintenance state and schedule
+   *     tags: [Automations]
+   *     parameters:
+   *       - in: path
+   *         name: hostId
+   *         required: true
+   *         schema: { type: integer }
+   *     responses:
+   *       200: { description: The active window, if any, and the planned ones. }
+   *       404: { description: Not one of the caller's hosts. }
+   */
   router.get(
     "/maintenance/:hostId",
     ctx.rbac.require("view") as never,
     handle(false),
   );
+  /**
+   * @openapi
+   * /plugin-api/automations/maintenance/{hostId}:
+   *   post:
+   *     summary: Start, schedule, end or remove maintenance on a host
+   *     description: While a host is in maintenance its downtime does not raise alerts. Past the estimated end plus the grace period, it can alert again.
+   *     tags: [Automations]
+   *     parameters:
+   *       - in: path
+   *         name: hostId
+   *         required: true
+   *         schema: { type: integer }
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [action]
+   *             properties:
+   *               action: { type: string, enum: [start, schedule, end, remove] }
+   *               reason: { type: string }
+   *               start: { type: string, format: date-time, description: When a scheduled window begins. }
+   *               durationMinutes: { type: integer, description: Estimated length. }
+   *               graceMinutes: { type: integer }
+   *               recurrence: { type: string, description: Repeat a scheduled window, e.g. weekly or monthly. }
+   *     responses:
+   *       200: { description: The new maintenance state. }
+   *       400: { description: Invalid action or plan. }
+   *       404: { description: Not one of the caller's hosts. }
+   */
   router.post(
     "/maintenance/:hostId",
     ctx.rbac.require("edit") as never,