u

src/api/routes/docs.js

@@ -4,6 +4,8 @@ import { getOpenApiSpec } from '../openapiSpec.js';
 
 const swaggerDistPath = swaggerUiDist.getAbsoluteFSPath();
 
+// #region Helpers
+
 function renderDocsHtml() {
     return `<!DOCTYPE html>
 <html lang="en">
@@ -56,6 +58,8 @@ function renderDocsHtml() {
 </html>`;
 }
 
+// #endregion
+
 /**
  * Registers documentation and interactive API tester under /docs/.
  * @param {import('express').Application} app - Express app
@@ -64,6 +68,8 @@ function renderDocsHtml() {
 export function register(app, basePath = '') {
     const docsRouter = express.Router();
 
+    // #region USE /docs (redirect)
+
     // Redirect /docs (or /api/docs) to /docs/ so relative assets resolve properly
     docsRouter.use((req, res, next) => {
         const rawPath = req.originalUrl.split('?')[0];
@@ -74,6 +80,10 @@ export function register(app, basePath = '') {
         next();
     });
 
+    // #endregion
+
+    // #region GET /openapi.json
+
     // Serve OpenAPI 3.0 specification JSON
     docsRouter.get('/openapi.json', (_req, res) => {
         try {
@@ -86,26 +96,48 @@ export function register(app, basePath = '') {
         }
     });
 
+    // #endregion
+
+    // #region GET /
+
     // Serve HTML UI for /docs/ and /docs/index.html
     docsRouter.get('/', (_req, res) => {
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.send(renderDocsHtml());
     });
 
+    // #endregion
+
+    // #region GET /index.html
+
     docsRouter.get('/index.html', (_req, res) => {
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.send(renderDocsHtml());
     });
 
+    // #endregion
+
+    // #region USE /docs (static assets)
+
     // Serve static assets from swagger-ui-dist (CSS, JS bundles, icons)
     docsRouter.use(express.static(swaggerDistPath, { index: false }));
 
+    // #endregion
+
+    // #region USE /docs
+
     // Mount on /docs
     app.use('/docs', docsRouter);
 
+    // #endregion
+
+    // #region USE <basePath>/docs
+
     // Also mount on /api/docs and alias /api/openapi.json if basePath is set
     if (basePath) {
         app.use(basePath + '/docs', docsRouter);
         app.get(basePath + '/openapi.json', (_req, res) => res.redirect(301, '/docs/openapi.json'));
     }
+
+    // #endregion
 }