feat: interactive OpenAPI/Swagger API docs

backend/package.json

@@ -18,7 +18,8 @@
     "test:smoke": "jest -c tests/smoke/jest.smoke.config.js",
     "test:smoke:verbose": "VERBOSE=1 jest -c tests/smoke/jest.smoke.config.js --verbose",
     "setup:smoke-user": "ts-node ../scripts/setup-smoke-test-user.ts",
-    "swagger:export": "ts-node scripts/export-swagger.ts",
+    "swagger:export": "npm run openapi:generate && ts-node scripts/export-swagger.ts",
+    "openapi:generate": "ts-node scripts/generate-openapi-paths.ts",
     "db:migrate": "supabase db push",
     "db:migrate:prod": "supabase db push --db-url \"$PRODUCTION_DB_URL\"",
     "db:reset": "supabase db reset",
@@ -65,6 +66,7 @@
     "rate-limit-redis": "^4.3.1",
     "redis": "^6.0.0",
     "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
     "telegraf": "^4.16.3",
     "uuid": "^14.0.1",
     "web-push": "^3.6.7",

backend/scripts/generate-openapi-paths.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates OpenAPI path JSDoc blocks from route comments and registrations.
+ * Run with: npm run openapi:generate
+ */
+import * as path from 'path';
+import { generateOpenApiPathsFile } from '../src/openapi/route-generator';
+
+const outputPath = path.join(__dirname, '..', 'src', 'openapi', 'generated-paths.ts');
+const count = generateOpenApiPathsFile(outputPath);
+console.log(`Generated ${count} OpenAPI paths at ${outputPath}`);

backend/src/index.ts

@@ -225,6 +225,12 @@ app.get('/health', async (req, res) => {
 });
 
 // Swagger Documentation
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+app.get('/api-docs.json', (_req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+  res.send(swaggerSpec);
+});
+// Legacy aliases
 app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
 app.get('/api/docs.json', (_req, res) => {
   res.setHeader('Content-Type', 'application/json');