feat(swagger): mount Swagger UI at /api/swagger

- Import swagger-ui-express, swagger-jsdoc, yamljs in app.js and index.js
- Load server/openapi.yaml as base spec
- Configure swagger-jsdoc to merge JSDoc comments from route files
- Mount Swagger UI at /api/swagger (publicly accessible)
- Add authentication banner explaining cookie + CSRF flow
- Ensure spec loads from both createApp (tests) and index.js (production)

server/index.js

@@ -8,6 +8,9 @@ const crypto = require('crypto');
 const fs = require('fs');
 const http = require('http');
 const https = require('https');
+const swaggerUi = require('swagger-ui-express');
+const swaggerJsdoc = require('swagger-jsdoc');
+const YAML = require('yamljs');
 require('dotenv').config();
 require('./utils/loadSecrets')();
 const { version } = require('../package.json');
@@ -113,6 +116,23 @@ if (process.env.EMBY_URL) {
 const app = express();
 const PORT = process.env.PORT || 3001;
 
+// Load OpenAPI spec from YAML
+const openapiSpec = YAML.load(path.join(__dirname, 'openapi.yaml'));
+
+// Configure swagger-jsdoc to merge JSDoc comments from route files
+const swaggerOptions = {
+  definition: {
+    ...openapiSpec,
+    openapi: '3.1.0'
+  },
+  apis: [
+    path.join(__dirname, 'routes/*.js'),
+    path.join(__dirname, 'index.js')
+  ]
+};
+
+const swaggerSpec = swaggerJsdoc(swaggerOptions);
+
 // Resolve TLS_ENABLED early — used in Helmet CSP and server startup
 const TLS_ENABLED = (process.env.TLS_ENABLED || 'true').toLowerCase() !== 'false';
 
@@ -212,6 +232,17 @@ app.get('/ready', (req, res) => {
   }
 });
 
+// ---------------------------------------------------------------------------
+// Swagger UI - publicly accessible API documentation
+// ---------------------------------------------------------------------------
+app.use('/api/swagger', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
+  customSiteTitle: 'sofarr API Documentation',
+  customCss: '.swagger-ui .topbar { display: none }',
+  customJs: [
+    '/swagger-auth-banner.js'
+  ]
+}));
+
 // ---------------------------------------------------------------------------
 // Static files — served before API routes
 // index.html is served manually so we can inject the CSP nonce