mockapi-msi 2.4.0 → 2.5.0

package/README.md

@@ -6,6 +6,12 @@ MockAPI let you create fake responses with pre defined and dynamic data for defi
 
 MockAPI also is intended to help you when, during testing phase, you cannot afford complex and expensive products (And you do not need them) that requires bulky configuration steps or depends directly on third party providers that you cannot control.
 
+## Version 2.5.0 notes
+
+- **OpenAPI JSON endpoint**: MockAPI now generates and serves an OpenAPI document at `/openapi.json` based on your configured endpoints.
+- **Interactive docs page**: Swagger UI is available at `/docs`, allowing users to inspect and try endpoints directly from the browser.
+- **OpenAPI configuration**: New optional `openApi` section allows enabling/disabling docs and overriding docs/spec paths and metadata.
+
 ## Version 2.4.0 notes
 
 - **HTTPS support**: New `tls` configuration option with `cert` and `key` paths. When provided, MockAPI starts an HTTPS server instead of HTTP.
@@ -66,6 +72,8 @@ Edit ```.mockapi-config``` to add your own endpoints, responses, parsers and dat
 
 **staticPath** - Optional configuration. Path to a local directory to serve static files from. Requests that don't match any endpoint will fall back to static file serving.
 
+**openApi** - Optional configuration to enable/disable generated OpenAPI docs and customize routes and document metadata.
+
 **data** - 
 Holds and describe the available data for all endpoints and responses.
 
@@ -164,6 +172,36 @@ The previous example will wait ```2000ms``` before sending the response, which i
 
 MockAPI watches the ```.mockapi-config``` file for changes. When the file is saved, endpoints and data sources are automatically reloaded without restarting the server. This allows you to add, remove, or modify endpoints while the server is running.
 
+#### OpenAPI docs
+
+MockAPI can auto-generate OpenAPI docs from your configured endpoints and expose them with built-in routes:
+
+- ``/openapi.json`` - generated OpenAPI document
+- ``/docs`` - Swagger UI page powered by the generated document
+
+These routes update automatically when `.mockapi-config` changes (hot-reload).
+The `/docs` page loads Swagger UI assets from `unpkg.com`.
+
+To customize or disable this feature, use the optional `openApi` section:
+
+```yaml
+openApi:
+  enabled: true
+  docsPath: "/docs"
+  specPath: "/openapi.json"
+  info:
+    title: "My Mock API"
+    version: "1.0.0"
+    description: "Generated from MockAPI configuration."
+```
+
+Disable docs completely:
+
+```yaml
+openApi:
+  enabled: false
+```
+
 #### CORS configuration
 
 CORS can be configured in three ways:
@@ -316,4 +354,4 @@ docker run -p 3001:8001 \
   -v $(pwd)/testdata:/usr/src/app/testdata \
   -v $(pwd)/apiHandlers:/usr/src/app/apiHandlers \
   mockapi
-```
+```

package/modules/cli.js

@@ -15,6 +15,9 @@ class CLI {
     _configTemplate = {
         port: 8080,
         enableCors: true,
+        openApi: {
+          enabled: true
+        },
         data: {
           myRows: { path: 'YOUR FOLDER', reader: 'folder' }
         },
@@ -104,4 +107,4 @@ class CLI {
     }
 }
 
-module.exports = CLI;
+module.exports = CLI;

package/modules/core.js

@@ -5,6 +5,7 @@ const path = require('path');
 const fs = require('fs');
 const constants = require('./constants');
 const handlerLoader = require('./configurationParser');
+const openApi = require('./openApi');
 
 const MIME_TYPES = {
     '.html': 'text/html',
@@ -35,6 +36,8 @@ class Core {
     _staticPath = null;
     _connections = new Set();
     _tls = null;
+    _openApi = null;
+    _openApiSpec = null;
 
     constructor(logger, configurations, modulesProxy) {
         this._configurations = configurations;
@@ -45,9 +48,11 @@ class Core {
         this._modulesProxy = modulesProxy;
         this._staticPath = configurations.staticPath || null;
         this._tls = this._parseTls(configurations.tls);
+        this._openApi = this._parseOpenApi(configurations.openApi);
 
         this._data = configurations.data || { };
         handlerLoader.loadHandlersFromConfiguration(this._data);
+        this._refreshOpenApiSpec();
     }
 
     _parseTls(tlsConfig) {
@@ -78,6 +83,63 @@ class Core {
         };
     }
 
+    _normalizeRoutePath(routePath, fallbackPath) {
+        if (typeof routePath !== 'string' || routePath.trim() === '') return fallbackPath;
+
+        let normalized = routePath.trim();
+
+        if (!normalized.startsWith('/')) {
+            normalized = `/${normalized}`;
+        }
+
+        if (normalized.length > 1 && normalized.endsWith('/')) {
+            normalized = normalized.slice(0, -1);
+        }
+
+        return normalized;
+    }
+
+    _parseOpenApi(openApiConfig) {
+        const defaultConfig = {
+            enabled: true,
+            docsPath: '/docs',
+            specPath: '/openapi.json',
+            title: 'MockAPI',
+            version: '1.0.0',
+            description: 'OpenAPI definition generated from .mockapi-config.'
+        };
+
+        if (openApiConfig === false) {
+            return {
+                ...defaultConfig,
+                enabled: false
+            };
+        }
+
+        if (openApiConfig === true || openApiConfig === undefined || openApiConfig === null) {
+            return defaultConfig;
+        }
+
+        if (typeof openApiConfig !== 'object') {
+            return defaultConfig;
+        }
+
+        const infoConfig = openApiConfig.info || {};
+
+        return {
+            enabled: openApiConfig.enabled !== false,
+            docsPath: this._normalizeRoutePath(openApiConfig.docsPath, defaultConfig.docsPath),
+            specPath: this._normalizeRoutePath(openApiConfig.specPath, defaultConfig.specPath),
+            title: infoConfig.title || openApiConfig.title || defaultConfig.title,
+            version: infoConfig.version || openApiConfig.version || defaultConfig.version,
+            description: infoConfig.description || openApiConfig.description || defaultConfig.description
+        };
+    }
+
+    _refreshOpenApiSpec() {
+        this._openApiSpec = openApi.buildSpec(this._openApi, this._endpointList);
+    }
+
     _applyCorsHeaders(request, response) {
         if (!this._cors) return false;
 
@@ -134,6 +196,30 @@ class Core {
         return true;
     }
 
+    _handleOpenApiRequest(request, response, pathName) {
+        if (!this._openApi || this._openApi.enabled === false || request.method !== 'GET') {
+            return false;
+        }
+
+        if (pathName === this._openApi.specPath) {
+            response.statusCode = constants.HTTP_STATUS_CODES.OK;
+            response.setHeader('Content-Type', 'application/json');
+            this._applyCorsHeaders(request, response);
+            response.end(JSON.stringify(this._openApiSpec, null, 2));
+            return true;
+        }
+
+        if (pathName === this._openApi.docsPath || pathName === `${this._openApi.docsPath}/`) {
+            response.statusCode = constants.HTTP_STATUS_CODES.OK;
+            response.setHeader('Content-Type', 'text/html; charset=utf-8');
+            this._applyCorsHeaders(request, response);
+            response.end(openApi.buildDocsPage(this._openApi));
+            return true;
+        }
+
+        return false;
+    }
+
     run() {
         const self = this;
 
@@ -147,6 +233,12 @@ class Core {
                 return;
             }
 
+            const urlInformation = parser.parse(request.url);
+
+            if (self._handleOpenApiRequest(request, response, urlInformation.pathname)) {
+                return;
+            }
+
             let bodyPayload = [];
         
             request.on('data', (chunk) => {
@@ -154,8 +246,6 @@ class Core {
             }).on('end', () => {
                 bodyPayload = Buffer.concat(bodyPayload).toString();
         
-                const urlInformation = parser.parse(request.url);
-        
                 self._logger.info(`Requesting: ${urlInformation.base} - Verb: ${request.method}`);
         
                 if (bodyPayload !== '') {
@@ -266,9 +356,11 @@ class Core {
         this._cors = this._parseCors(configurations.enableCors);
         this._endpointList = configurations.endpoints;
         this._staticPath = configurations.staticPath || null;
+        this._openApi = this._parseOpenApi(configurations.openApi);
 
         this._data = configurations.data || {};
         handlerLoader.loadHandlersFromConfiguration(this._data);
+        this._refreshOpenApiSpec();
 
         this._logger.info('Configuration reloaded');
     }
@@ -286,4 +378,4 @@ class Core {
     }
 }
 
-module.exports = Core;
+module.exports = Core;

package/modules/openApi.js

@@ -0,0 +1,178 @@
+const http = require('http');
+const constants = require('./constants');
+
+const OPENAPI_VERSION = '3.1.0';
+const DEFAULT_METHODS_FOR_ANY = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+const normalizeMethod = (verb) => {
+    if (typeof verb !== 'string' || verb.trim() === '') return ['get'];
+
+    const method = verb.toLowerCase();
+    return method === 'any' ? DEFAULT_METHODS_FOR_ANY : [method];
+};
+
+const toOpenApiPath = (endpointPath) => {
+    if (typeof endpointPath !== 'string' || endpointPath.trim() === '') return '/';
+    return endpointPath.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+};
+
+const extractPathParameters = (endpointPath) => {
+    if (typeof endpointPath !== 'string' || endpointPath.trim() === '') return [];
+
+    const pathParameters = endpointPath.match(/:([A-Za-z0-9_]+)/g) || [];
+
+    return pathParameters.map((parameter) => ({
+        name: parameter.substring(1),
+        in: 'path',
+        required: true,
+        schema: { type: 'string' }
+    }));
+};
+
+const getResponseStatusCode = (endpointConfiguration) => {
+    const status = parseInt(endpointConfiguration.responseStatus, 10);
+
+    if (!Number.isNaN(status) && status >= 100 && status <= 599) {
+        return status;
+    }
+
+    return constants.HTTP_STATUS_CODES.OK;
+};
+
+const buildResponseContent = (contentType) => {
+    if (!contentType) return undefined;
+
+    const isJsonContentType = contentType.toLowerCase().includes('json');
+
+    return {
+        [contentType]: {
+            schema: isJsonContentType ? {} : { type: 'string' }
+        }
+    };
+};
+
+const buildOperation = (method, endpointPath, endpointConfiguration) => {
+    const responseStatusCode = getResponseStatusCode(endpointConfiguration);
+    const responseContentType = endpointConfiguration.responseContentType || constants.DEFAULT_CONTENT_TYPE;
+    const responseDescription = http.STATUS_CODES[responseStatusCode] || 'Configured response';
+
+    const operation = {
+        summary: `${method.toUpperCase()} ${toOpenApiPath(endpointPath)}`,
+        responses: {
+            [responseStatusCode]: {
+                description: responseDescription
+            }
+        }
+    };
+
+    const responseContent = buildResponseContent(responseContentType);
+    if (responseContent !== undefined) {
+        operation.responses[responseStatusCode].content = responseContent;
+    }
+
+    const parameters = extractPathParameters(endpointPath);
+    if (parameters.length > 0) {
+        operation.parameters = parameters;
+    }
+
+    const metadata = {};
+    if (endpointConfiguration.data !== undefined) metadata.data = endpointConfiguration.data;
+    if (endpointConfiguration.handler !== undefined) metadata.handler = endpointConfiguration.handler;
+    if (endpointConfiguration.delay !== undefined) metadata.delay = endpointConfiguration.delay;
+
+    if (Object.keys(metadata).length > 0) {
+        operation['x-mockapi'] = metadata;
+    }
+
+    return operation;
+};
+
+const buildSpec = (settings, endpointList) => {
+    const openApiSettings = settings || {};
+    const endpoints = endpointList || {};
+    const paths = {};
+
+    for (const endpointPath in endpoints) {
+        if (!Object.hasOwnProperty.call(endpoints, endpointPath)) continue;
+
+        const endpointConfiguration = endpoints[endpointPath] || {};
+        const openApiPath = toOpenApiPath(endpointPath);
+
+        if (!paths[openApiPath]) {
+            paths[openApiPath] = {};
+        }
+
+        const methods = normalizeMethod(endpointConfiguration.verb);
+        for (const method of methods) {
+            paths[openApiPath][method] = buildOperation(method, endpointPath, endpointConfiguration);
+        }
+    }
+
+    return {
+        openapi: OPENAPI_VERSION,
+        info: {
+            title: openApiSettings.title || 'MockAPI',
+            version: openApiSettings.version || '1.0.0',
+            description: openApiSettings.description || 'OpenAPI definition generated from .mockapi-config.'
+        },
+        servers: [{ url: '/' }],
+        paths
+    };
+};
+
+const escapeHtml = (value) => String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
+const escapeJsString = (value) => String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'");
+
+const buildDocsPage = (settings) => {
+    const docsSettings = settings || {};
+    const title = escapeHtml(docsSettings.title || 'MockAPI');
+    const specPath = escapeJsString(docsSettings.specPath || '/openapi.json');
+
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title} - API Docs</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      html, body {
+        margin: 0;
+        background: #f6f8fa;
+      }
+      #swagger-ui {
+        min-height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = function() {
+        window.ui = SwaggerUIBundle({
+          url: '${specPath}',
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis],
+          layout: 'BaseLayout'
+        });
+      };
+    </script>
+  </body>
+</html>`;
+};
+
+module.exports = {
+    buildSpec,
+    buildDocsPage,
+    toOpenApiPath
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mockapi-msi",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Mock API is a lightweight configurable HTTP API for testing and prototyping.",
   "main": "main.js",
   "scripts": {