feat(docs): replace swagger-ui-express with Scalar + /api/spec.json (#3388)

* feat(docs): replace swagger-ui-express with Scalar + /api/spec.json (#3385)

- Remove swagger-ui-express, install @scalar/express-api-reference
- Rewrite initSwagger(): serve merged OpenAPI spec at GET /api/spec.json,
  mount Scalar UI at /api/docs
- Remove file write to ./public/swagger.yml and unused swagger config options
- Add 3 unit tests for initSwagger (enabled, spec JSON, disabled)

* docs(migrations): add Scalar replaces swagger-ui-express entry

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -4,6 +4,28 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## Scalar replaces swagger-ui-express (2026-04-04)
+
+`swagger-ui-express` has been removed. The API documentation UI is now powered by [Scalar](https://scalar.com/) via `@scalar/express-api-reference`.
+
+### What changed
+
+- `initSwagger()` in `lib/services/express.js` no longer writes `./public/swagger.yml` to disk
+- New endpoint `GET /api/spec.json` serves the merged OpenAPI spec as JSON
+- `/api/docs` now serves the Scalar UI instead of Swagger UI
+- Removed unused swagger config options: `swaggerUrl`, `explore`
+- Removed dependency: `swagger-ui-express`
+- Added dependency: `@scalar/express-api-reference`
+
+### Action for downstream
+
+1. Run `/update-stack` to pull the change
+2. Remove any references to `./public/swagger.yml` — it is no longer generated
+3. If you customized swagger options (e.g. `swaggerUrl`, `explore`), remove them — they are no longer used
+4. The `/api/docs` and `/api/spec.json` routes are available as before
+
+---
+
 ## Module Activation Config (2026-04-05)
 
 Per-module `activated: true/false` config flag. When `activated: false`, the module's routes, policies, models, and swagger YAML are excluded from the app entirely.

config/defaults/development.config.js

@@ -8,10 +8,6 @@ const config = {
   },
   swagger: {
     enable: true,
-    options: {
-      swaggerUrl: '/api/docs/swagger.yml',
-      explore: true,
-    },
   },
   api: {
     protocol: 'http',

lib/services/express.js

@@ -15,7 +15,7 @@ import cors from 'cors';
 import morgan from 'morgan';
 import fs from 'fs';
 import YAML from 'js-yaml';
-import swaggerUi from 'swagger-ui-express';
+import { apiReference } from '@scalar/express-api-reference';
 
 import config from '../../config/index.js';
 import logger from './logger.js';
@@ -25,25 +25,26 @@ import AnalyticsService from './analytics.js';
 import analyticsMiddleware from '../middlewares/analytics.js';
 
 /**
- * Initialize Swagger
+ * Initialize API documentation (Scalar UI + JSON spec endpoint)
  */
 const initSwagger = (app) => {
   if (config.swagger.enable) {
-    // Merge files.
-    try {
-      const contents = config.files.swagger.map((filePath) => YAML.load(fs.readFileSync(filePath).toString()));
-      const merged = contents.reduce(_.merge);
-      fs.writeFile('./public/swagger.yml', YAML.dump(merged), (error) => {
-        if (error) {
-          throw error;
-        }
-      });
-    } catch (e) {
-      throw new Error(e);
-    }
+    // Merge all module OpenAPI YAML files into a single spec
+    const contents = config.files.swagger.map((filePath) => YAML.load(fs.readFileSync(filePath).toString()));
+    const spec = contents.reduce(_.merge);
+
+    // Serve the merged spec as JSON
+    app.get('/api/spec.json', (req, res) => {
+      res.json(spec);
+    });
 
-    app.use(config.swagger.options.swaggerUrl, express.static('./public/swagger.yml'));
-    app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(null, config.swagger.options));
+    // Mount Scalar API reference UI
+    app.use(
+      '/api/docs',
+      apiReference({
+        spec: { content: spec },
+      }),
+    );
   }
 };
 

modules/audit/tests/audit.middleware.unit.tests.js

@@ -83,7 +83,7 @@ describe('Audit middleware unit tests:', () => {
     const middleware = createAuditMiddleware();
     const next = jest.fn();
 
-    const prefixes = ['/public/file.js', '/favicon.ico', '/api/docs/swagger', '/api/health'];
+    const prefixes = ['/public/file.js', '/favicon.ico', '/api/docs', '/api/health'];
     for (const url of prefixes) {
       const req = createReq({ method: 'POST', originalUrl: url });
       const res = createRes();

modules/core/tests/core.unit.tests.js

@@ -466,6 +466,58 @@ describe('Core unit tests:', () => {
   });
 
   describe('Express service', () => {
+    describe('initSwagger', () => {
+      let originalSwagger;
+      let originalFiles;
+
+      beforeEach(() => {
+        originalSwagger = config.swagger;
+        originalFiles = config.files;
+      });
+
+      afterEach(() => {
+        config.swagger = originalSwagger;
+        config.files = originalFiles;
+      });
+
+      it('should register /api/spec.json and /api/docs when swagger is enabled', () => {
+        config.swagger = { enable: true };
+        config.files = { ...config.files, swagger: [path.join(process.cwd(), 'modules/core/doc/index.yml')] };
+        const mockGet = jest.fn();
+        const mockUse = jest.fn();
+        const mockApp = { get: mockGet, use: mockUse };
+        expressService.initSwagger(mockApp);
+        expect(mockGet).toHaveBeenCalledWith('/api/spec.json', expect.any(Function));
+        expect(mockUse).toHaveBeenCalledWith('/api/docs', expect.any(Function));
+      });
+
+      it('should serve merged spec as JSON from /api/spec.json handler', () => {
+        config.swagger = { enable: true };
+        config.files = { ...config.files, swagger: [path.join(process.cwd(), 'modules/core/doc/index.yml')] };
+        const mockGet = jest.fn();
+        const mockUse = jest.fn();
+        const mockApp = { get: mockGet, use: mockUse };
+        expressService.initSwagger(mockApp);
+        // Extract the handler registered for /api/spec.json
+        const handler = mockGet.mock.calls.find((c) => c[0] === '/api/spec.json')[1];
+        const mockRes = { json: jest.fn() };
+        handler({}, mockRes);
+        expect(mockRes.json).toHaveBeenCalledWith(
+          expect.objectContaining({ openapi: '3.0.0' }),
+        );
+      });
+
+      it('should not register routes when swagger is disabled', () => {
+        config.swagger = { enable: false };
+        const mockGet = jest.fn();
+        const mockUse = jest.fn();
+        const mockApp = { get: mockGet, use: mockUse };
+        expressService.initSwagger(mockApp);
+        expect(mockGet).not.toHaveBeenCalled();
+        expect(mockUse).not.toHaveBeenCalled();
+      });
+    });
+
     describe('trust proxy', () => {
       let originalTrust;