docs(swagger): add JSDoc @openapi for public health endpoints

- GET /health: returns uptime, no auth/rate-limit
- GET /ready: checks EMBY_URL configuration, returns 503 if not ready
- Document Docker HEALTHCHECK usage

server/app.js

@@ -102,10 +102,75 @@ function createApp({ skipRateLimits = false } = {}) {
   app.use(express.json({ limit: '64kb' }));
 
   // Health / readiness (no auth, no rate-limit)
+  /**
+   * @openapi
+   * /health:
+   *   get:
+   *     tags: [Health]
+   *     summary: Health check
+   *     description: Returns server uptime and status. No authentication required. Used for liveness probes.
+   *     security: []
+   *     responses:
+   *       '200':
+   *         description: Server is healthy
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "ok"
+   *                 uptime:
+   *                   type: number
+   *                   description: Server uptime in seconds
+   *                   example: 3600.5
+   *     x-code-samples:
+   *       - lang: curl
+   *         label: cURL
+   *         source: curl http://localhost:3001/health
+   */
   app.get('/health', (req, res) => {
     res.json({ status: 'ok', uptime: process.uptime() });
   });
 
+  /**
+   * @openapi
+   * /ready:
+   *   get:
+   *     tags: [Health]
+   *     summary: Readiness check
+   *     description: Checks if critical configuration (EMBY_URL) is present. Used by Docker HEALTHCHECK and orchestrators. No authentication required.
+   *     security: []
+   *     responses:
+   *       '200':
+   *         description: Server is ready
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "ready"
+   *       '503':
+   *         description: Server not ready
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "not ready"
+   *                 reason:
+   *                   type: string
+   *                   example: "EMBY_URL not configured"
+   *     x-code-samples:
+   *       - lang: curl
+   *         label: cURL
+   *         source: curl http://localhost:3001/ready
+   */
   app.get('/ready', (req, res) => {
     const ready = !!(process.env.EMBY_URL);
     if (ready) {

server/index.js

@@ -218,10 +218,71 @@ app.use(express.json({ limit: '64kb' })); // prevent oversized JSON payloads
 // Health / readiness endpoints (no auth, no rate-limit)
 // Used by Docker HEALTHCHECK and orchestrators.
 // ---------------------------------------------------------------------------
+/**
+ * @openapi
+ * /health:
+ *   get:
+ *     tags: [Health]
+ *     summary: Health check
+ *     description: Returns server uptime and status. No authentication required. Used for liveness probes.
+ *     security: []
+ *     responses:
+ *       '200':
+ *         description: Server is healthy
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "ok"
+ *                 uptime:
+ *                   type: number
+ *                   description: Server uptime in seconds
+ *                   example: 3600.5
+ *                 version:
+ *                   type: string
+ *                   description: sofarr version
+ *                   example: "1.6.0"
+ */
 app.get('/health', (req, res) => {
   res.json({ status: 'ok', uptime: process.uptime(), version });
 });
 
+/**
+ * @openapi
+ * /ready:
+ *   get:
+ *     tags: [Health]
+ *     summary: Readiness check
+ *     description: Checks if critical configuration (EMBY_URL) is present. Used by Docker HEALTHCHECK and orchestrators. No authentication required.
+ *     security: []
+ *     responses:
+ *       '200':
+ *         description: Server is ready
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "ready"
+ *       '503':
+ *         description: Server not ready
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "not ready"
+ *                 reason:
+ *                   type: string
+ *                   example: "EMBY_URL not configured"
+ */
 app.get('/ready', (req, res) => {
   // Confirm critical config is present
   const ready = !!(process.env.EMBY_URL);