@digitaldefiance/node-express-suite 3.11.31 → 3.12.0

package/src/openapi/controller.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Generic OpenAPI documentation controller.
+ * Serves the OpenAPI specification built from registered controllers.
+ * Supports JSON and YAML formats, tag filtering, and external documentation.
+ * @module openapi/controller
+ */
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { Router } from 'express';
+import { IApplication } from '../interfaces/application';
+import { OpenAPIBuilder, OpenAPIBuilderConfig, OpenAPISpec } from './builder';
+/**
+ * Response type for the OpenAPI endpoint.
+ */
+export interface OpenAPIResponse {
+    message: string;
+    openapi: string;
+    info: OpenAPISpec['info'];
+    servers: OpenAPISpec['servers'];
+    paths: OpenAPISpec['paths'];
+    components: OpenAPISpec['components'];
+    externalDocs?: OpenAPISpec['externalDocs'];
+    tags?: OpenAPISpec['tags'];
+}
+/**
+ * Options for configuring the OpenAPI controller.
+ */
+export interface OpenAPIControllerOptions {
+    /** Whether to cache the spec (default: true in production) */
+    cacheSpec?: boolean;
+    /** Enable YAML format endpoint at /yaml (default: false) */
+    enableYaml?: boolean;
+    /** Enable tag filtering via ?tags query parameter (default: true) */
+    enableTagFiltering?: boolean;
+    /** Custom base path for the spec endpoints (default: '') */
+    basePath?: string;
+}
+/**
+ * Generic OpenAPI documentation controller.
+ * Serves the OpenAPI specification at the configured endpoint.
+ *
+ * Unlike other controllers, this one doesn't extend BaseController to avoid
+ * circular dependencies and keep it lightweight. It's designed to be mounted
+ * directly on a router.
+ *
+ * Features:
+ * - JSON format at / and /json
+ * - Optional YAML format at /yaml
+ * - Tag filtering via ?tags=tag1,tag2 query parameter
+ * - Caching support for production environments
+ * - External documentation support
+ *
+ * @example
+ * ```typescript
+ * // In your API router setup:
+ * const openApiController = new OpenAPIController(application, {
+ *   title: 'My API',
+ *   version: '1.0.0',
+ *   description: 'My awesome API',
+ *   externalDocs: {
+ *     description: 'Full documentation',
+ *     url: 'https://docs.example.com'
+ *   }
+ * }, {
+ *   enableYaml: true,
+ *   enableTagFiltering: true
+ * });
+ * router.use('/openapi', openApiController.router);
+ * ```
+ */
+export declare class OpenAPIController<TID extends PlatformID = Buffer> {
+    readonly router: Router;
+    private readonly builder;
+    private readonly applicationRef;
+    private cachedSpec;
+    private readonly cacheEnabled;
+    private readonly enableYaml;
+    private readonly enableTagFiltering;
+    /**
+     * Create a new OpenAPI controller.
+     * @param application - The application instance
+     * @param config - OpenAPI builder configuration
+     * @param options - Controller options
+     */
+    constructor(application: IApplication<TID>, config: OpenAPIBuilderConfig, options?: OpenAPIControllerOptions);
+    /**
+     * Get the application instance.
+     * Useful for accessing application configuration or services.
+     */
+    get application(): IApplication<TID>;
+    /**
+     * Initialize the routes.
+     */
+    private initializeRoutes;
+    /**
+     * Handle GET request for the OpenAPI specification in JSON format.
+     */
+    private handleGetSpec;
+    /**
+     * Handle GET request for the raw OpenAPI specification without wrapper.
+     */
+    private handleGetRawSpec;
+    /**
+     * Handle GET request for the OpenAPI specification in YAML format.
+     */
+    private handleGetSpecYaml;
+    /**
+     * Filter the OpenAPI spec to only include paths with specified tags.
+     * @param spec - The full OpenAPI spec
+     * @param tags - Tags to filter by
+     * @returns Filtered spec
+     */
+    private filterSpecByTags;
+    /**
+     * Convert the OpenAPI spec to YAML format.
+     * Uses a simple JSON-to-YAML conversion without external dependencies.
+     * @param spec - The OpenAPI spec object
+     * @returns YAML string representation
+     */
+    private convertToYaml;
+    /**
+     * Simple JSON to YAML converter.
+     * @param obj - Object to convert
+     * @param indent - Current indentation level
+     * @returns YAML string
+     */
+    private jsonToYaml;
+    /**
+     * Get the OpenAPI specification, using cache if enabled.
+     */
+    private getSpec;
+    /**
+     * Clear the cached specification.
+     * Useful when routes are dynamically added.
+     */
+    clearCache(): void;
+    /**
+     * Get the raw OpenAPI specification object.
+     * Useful for programmatic access or testing.
+     */
+    getSpecification(): OpenAPISpec;
+    /**
+     * Get the OpenAPI specification filtered by tags.
+     * @param tags - Tags to filter by
+     * @returns Filtered OpenAPI spec
+     */
+    getSpecificationByTags(tags: string[]): OpenAPISpec;
+    /**
+     * Get the OpenAPI builder instance.
+     * Useful for advanced customization.
+     */
+    getBuilder(): OpenAPIBuilder;
+}
+//# sourceMappingURL=controller.d.ts.map

package/src/openapi/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/openapi/controller.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,iBAAiB,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM;IAC5D,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAE7C;;;;;OAKG;gBAED,WAAW,EAAE,YAAY,CAAC,GAAG,CAAC,EAC9B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,CAAC,EAAE,wBAAwB;IAapC;;;OAGG;IACH,IAAW,WAAW,IAAI,YAAY,CAAC,GAAG,CAAC,CAE1C;IAED;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,OAAO,CAAC,aAAa;IA2CrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IA0ElB;;OAEG;IACH,OAAO,CAAC,OAAO;IAcf;;;OAGG;IACI,UAAU,IAAI,IAAI;IAIzB;;;OAGG;IACI,gBAAgB,IAAI,WAAW;IAItC;;;;OAIG;IACI,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW;IAI1D;;;OAGG;IACI,UAAU,IAAI,cAAc;CAGpC"}

package/src/openapi/controller.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * @fileoverview Generic OpenAPI documentation controller.
+ * Serves the OpenAPI specification built from registered controllers.
+ * Supports JSON and YAML formats, tag filtering, and external documentation.
+ * @module openapi/controller
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAPIController = void 0;
+const express_1 = require("express");
+const builder_1 = require("./builder");
+/**
+ * Generic OpenAPI documentation controller.
+ * Serves the OpenAPI specification at the configured endpoint.
+ *
+ * Unlike other controllers, this one doesn't extend BaseController to avoid
+ * circular dependencies and keep it lightweight. It's designed to be mounted
+ * directly on a router.
+ *
+ * Features:
+ * - JSON format at / and /json
+ * - Optional YAML format at /yaml
+ * - Tag filtering via ?tags=tag1,tag2 query parameter
+ * - Caching support for production environments
+ * - External documentation support
+ *
+ * @example
+ * ```typescript
+ * // In your API router setup:
+ * const openApiController = new OpenAPIController(application, {
+ *   title: 'My API',
+ *   version: '1.0.0',
+ *   description: 'My awesome API',
+ *   externalDocs: {
+ *     description: 'Full documentation',
+ *     url: 'https://docs.example.com'
+ *   }
+ * }, {
+ *   enableYaml: true,
+ *   enableTagFiltering: true
+ * });
+ * router.use('/openapi', openApiController.router);
+ * ```
+ */
+class OpenAPIController {
+    router;
+    builder;
+    applicationRef;
+    cachedSpec = null;
+    cacheEnabled;
+    enableYaml;
+    enableTagFiltering;
+    /**
+     * Create a new OpenAPI controller.
+     * @param application - The application instance
+     * @param config - OpenAPI builder configuration
+     * @param options - Controller options
+     */
+    constructor(application, config, options) {
+        this.applicationRef = application;
+        this.builder = new builder_1.OpenAPIBuilder(config);
+        this.router = (0, express_1.Router)();
+        this.cacheEnabled =
+            options?.cacheSpec ?? process.env.NODE_ENV === 'production';
+        this.enableYaml = options?.enableYaml ?? false;
+        this.enableTagFiltering = options?.enableTagFiltering ?? true;
+        this.initializeRoutes();
+    }
+    /**
+     * Get the application instance.
+     * Useful for accessing application configuration or services.
+     */
+    get application() {
+        return this.applicationRef;
+    }
+    /**
+     * Initialize the routes.
+     */
+    initializeRoutes() {
+        // GET / - Returns the OpenAPI specification in JSON
+        this.router.get('/', this.handleGetSpec.bind(this));
+        // GET /json - Alias for the spec in JSON
+        this.router.get('/json', this.handleGetSpec.bind(this));
+        // GET /yaml - Returns the OpenAPI specification in YAML (if enabled)
+        if (this.enableYaml) {
+            this.router.get('/yaml', this.handleGetSpecYaml.bind(this));
+        }
+        // GET /raw - Returns the raw spec without wrapper
+        this.router.get('/raw', this.handleGetRawSpec.bind(this));
+    }
+    /**
+     * Handle GET request for the OpenAPI specification in JSON format.
+     */
+    handleGetSpec(req, res) {
+        try {
+            let spec = this.getSpec();
+            // Apply tag filtering if enabled and tags query param is present
+            if (this.enableTagFiltering && req.query.tags) {
+                const tags = String(req.query.tags)
+                    .split(',')
+                    .map((t) => t.trim());
+                spec = this.filterSpecByTags(spec, tags);
+            }
+            const response = {
+                message: 'OpenAPI specification',
+                openapi: spec.openapi,
+                info: spec.info,
+                servers: spec.servers,
+                paths: spec.paths,
+                components: spec.components,
+            };
+            // Include optional fields if present
+            if (spec.externalDocs) {
+                response.externalDocs = spec.externalDocs;
+            }
+            if (spec.tags && spec.tags.length > 0) {
+                response.tags = spec.tags;
+            }
+            res.status(200).json(response);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: {
+                    code: 'OPENAPI_BUILD_ERROR',
+                    message: error instanceof Error
+                        ? error.message
+                        : 'Failed to build OpenAPI spec',
+                },
+            });
+        }
+    }
+    /**
+     * Handle GET request for the raw OpenAPI specification without wrapper.
+     */
+    handleGetRawSpec(req, res) {
+        try {
+            let spec = this.getSpec();
+            // Apply tag filtering if enabled and tags query param is present
+            if (this.enableTagFiltering && req.query.tags) {
+                const tags = String(req.query.tags)
+                    .split(',')
+                    .map((t) => t.trim());
+                spec = this.filterSpecByTags(spec, tags);
+            }
+            res.status(200).json(spec);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: {
+                    code: 'OPENAPI_BUILD_ERROR',
+                    message: error instanceof Error
+                        ? error.message
+                        : 'Failed to build OpenAPI spec',
+                },
+            });
+        }
+    }
+    /**
+     * Handle GET request for the OpenAPI specification in YAML format.
+     */
+    handleGetSpecYaml(req, res) {
+        try {
+            let spec = this.getSpec();
+            // Apply tag filtering if enabled and tags query param is present
+            if (this.enableTagFiltering && req.query.tags) {
+                const tags = String(req.query.tags)
+                    .split(',')
+                    .map((t) => t.trim());
+                spec = this.filterSpecByTags(spec, tags);
+            }
+            const yaml = this.convertToYaml(spec);
+            res.status(200).type('text/yaml').send(yaml);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: {
+                    code: 'OPENAPI_BUILD_ERROR',
+                    message: error instanceof Error
+                        ? error.message
+                        : 'Failed to build OpenAPI spec',
+                },
+            });
+        }
+    }
+    /**
+     * Filter the OpenAPI spec to only include paths with specified tags.
+     * @param spec - The full OpenAPI spec
+     * @param tags - Tags to filter by
+     * @returns Filtered spec
+     */
+    filterSpecByTags(spec, tags) {
+        const tagSet = new Set(tags.map((t) => t.toLowerCase()));
+        const filteredPaths = {};
+        for (const [path, methods] of Object.entries(spec.paths)) {
+            const filteredMethods = {};
+            for (const [method, operation] of Object.entries(methods)) {
+                const op = operation;
+                if (op.tags && op.tags.some((t) => tagSet.has(t.toLowerCase()))) {
+                    filteredMethods[method] = operation;
+                }
+            }
+            if (Object.keys(filteredMethods).length > 0) {
+                filteredPaths[path] = filteredMethods;
+            }
+        }
+        return {
+            ...spec,
+            paths: filteredPaths,
+        };
+    }
+    /**
+     * Convert the OpenAPI spec to YAML format.
+     * Uses a simple JSON-to-YAML conversion without external dependencies.
+     * @param spec - The OpenAPI spec object
+     * @returns YAML string representation
+     */
+    convertToYaml(spec) {
+        return this.jsonToYaml(spec, 0);
+    }
+    /**
+     * Simple JSON to YAML converter.
+     * @param obj - Object to convert
+     * @param indent - Current indentation level
+     * @returns YAML string
+     */
+    jsonToYaml(obj, indent) {
+        const spaces = '  '.repeat(indent);
+        if (obj === null || obj === undefined) {
+            return 'null';
+        }
+        if (typeof obj === 'string') {
+            // Check if string needs quoting
+            if (obj.includes('\n') ||
+                obj.includes(':') ||
+                obj.includes('#') ||
+                obj.startsWith(' ') ||
+                obj.endsWith(' ') ||
+                /^[0-9]/.test(obj) ||
+                obj === '' ||
+                ['true', 'false', 'null', 'yes', 'no'].includes(obj.toLowerCase())) {
+                return JSON.stringify(obj);
+            }
+            return obj;
+        }
+        if (typeof obj === 'number' || typeof obj === 'boolean') {
+            return String(obj);
+        }
+        if (Array.isArray(obj)) {
+            if (obj.length === 0) {
+                return '[]';
+            }
+            return obj
+                .map((item) => {
+                const itemYaml = this.jsonToYaml(item, indent + 1);
+                if (typeof item === 'object' &&
+                    item !== null &&
+                    !Array.isArray(item)) {
+                    return `${spaces}- ${itemYaml.trimStart()}`;
+                }
+                return `${spaces}- ${itemYaml}`;
+            })
+                .join('\n');
+        }
+        if (typeof obj === 'object') {
+            const entries = Object.entries(obj);
+            if (entries.length === 0) {
+                return '{}';
+            }
+            return entries
+                .map(([key, value]) => {
+                const valueYaml = this.jsonToYaml(value, indent + 1);
+                if (typeof value === 'object' &&
+                    value !== null &&
+                    !Array.isArray(value) &&
+                    Object.keys(value).length > 0) {
+                    return `${spaces}${key}:\n${valueYaml}`;
+                }
+                if (Array.isArray(value) && value.length > 0) {
+                    return `${spaces}${key}:\n${valueYaml}`;
+                }
+                return `${spaces}${key}: ${valueYaml}`;
+            })
+                .join('\n');
+        }
+        return String(obj);
+    }
+    /**
+     * Get the OpenAPI specification, using cache if enabled.
+     */
+    getSpec() {
+        if (this.cacheEnabled && this.cachedSpec) {
+            return this.cachedSpec;
+        }
+        const spec = this.builder.build();
+        if (this.cacheEnabled) {
+            this.cachedSpec = spec;
+        }
+        return spec;
+    }
+    /**
+     * Clear the cached specification.
+     * Useful when routes are dynamically added.
+     */
+    clearCache() {
+        this.cachedSpec = null;
+    }
+    /**
+     * Get the raw OpenAPI specification object.
+     * Useful for programmatic access or testing.
+     */
+    getSpecification() {
+        return this.getSpec();
+    }
+    /**
+     * Get the OpenAPI specification filtered by tags.
+     * @param tags - Tags to filter by
+     * @returns Filtered OpenAPI spec
+     */
+    getSpecificationByTags(tags) {
+        return this.filterSpecByTags(this.getSpec(), tags);
+    }
+    /**
+     * Get the OpenAPI builder instance.
+     * Useful for advanced customization.
+     */
+    getBuilder() {
+        return this.builder;
+    }
+}
+exports.OpenAPIController = OpenAPIController;
+//# sourceMappingURL=controller.js.map

package/src/openapi/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/openapi/controller.ts"],"names":[],"mappings":"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"}

package/src/openapi/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview OpenAPI module exports.
+ * Provides OpenAPI builder, controller, schemas, middleware, and documentation generators.
+ * @module openapi
+ */
+export { OpenAPIBuilder } from './builder';
+export type { OpenAPIBuilderConfig, OpenAPISpec, OpenAPIExternalDocs, OpenAPITagDefinition, OpenAPIOperationMetadata, OpenAPIParameter as BuilderOpenAPIParameter, OpenAPIParameterSchema as BuilderOpenAPIParameterSchema, OpenAPIRequestBody as BuilderOpenAPIRequestBody, OpenAPIResponse as BuilderOpenAPIResponse, } from './builder';
+export { OpenAPIController } from './controller';
+export type { OpenAPIControllerOptions, OpenAPIResponse as ControllerOpenAPIResponse, } from './controller';
+export * from './schemas';
+export * from './middleware';
+//# sourceMappingURL=index.d.ts.map

package/src/openapi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EAExB,gBAAgB,IAAI,uBAAuB,EAC3C,sBAAsB,IAAI,6BAA6B,EACvD,kBAAkB,IAAI,yBAAyB,EAC/C,eAAe,IAAI,sBAAsB,GAC1C,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,YAAY,EACV,wBAAwB,EACxB,eAAe,IAAI,yBAAyB,GAC7C,MAAM,cAAc,CAAC;AAGtB,cAAc,WAAW,CAAC;AAG1B,cAAc,cAAc,CAAC"}

package/src/openapi/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @fileoverview OpenAPI module exports.
+ * Provides OpenAPI builder, controller, schemas, middleware, and documentation generators.
+ * @module openapi
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAPIController = exports.OpenAPIBuilder = void 0;
+const tslib_1 = require("tslib");
+// Re-export builder class
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "OpenAPIBuilder", { enumerable: true, get: function () { return builder_1.OpenAPIBuilder; } });
+// Re-export controller class
+var controller_1 = require("./controller");
+Object.defineProperty(exports, "OpenAPIController", { enumerable: true, get: function () { return controller_1.OpenAPIController; } });
+// Schema registry
+tslib_1.__exportStar(require("./schemas"), exports);
+// Middleware (Swagger UI, ReDoc) and documentation generators
+tslib_1.__exportStar(require("./middleware"), exports);
+//# sourceMappingURL=index.js.map

package/src/openapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/openapi/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;AAEH,0BAA0B;AAC1B,qCAA2C;AAAlC,yGAAA,cAAc,OAAA;AAgBvB,6BAA6B;AAC7B,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAQ1B,kBAAkB;AAClB,oDAA0B;AAE1B,8DAA8D;AAC9D,uDAA6B"}

package/src/openapi/markdown-generator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Markdown documentation generator from OpenAPI specification.
+ * Generates comprehensive markdown documentation including table of contents,
+ * endpoints grouped by tag, parameters, and responses.
+ * @module openapi/markdown-generator
+ */
+import { OpenAPISpec } from './builder';
+/**
+ * Options for markdown documentation generation.
+ */
+export interface MarkdownGeneratorOptions {
+    /** Include table of contents (default: true) */
+    includeToc?: boolean;
+    /** Include API info section (default: true) */
+    includeInfo?: boolean;
+    /** Include server information (default: true) */
+    includeServers?: boolean;
+    /** Include authentication section (default: true) */
+    includeAuthentication?: boolean;
+    /** Include schema definitions (default: true) */
+    includeSchemas?: boolean;
+    /** Custom title override (uses spec title if not provided) */
+    title?: string;
+    /** Add anchor links to headings (default: true) */
+    anchorLinks?: boolean;
+}
+/**
+ * Generate markdown documentation from an OpenAPI specification.
+ *
+ * @param spec - The OpenAPI specification object
+ * @param options - Generation options
+ * @returns Generated markdown string
+ *
+ * @example
+ * ```typescript
+ * const spec = builder.build();
+ * const markdown = generateMarkdownDocs(spec);
+ * fs.writeFileSync('API.md', markdown);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const markdown = generateMarkdownDocs(spec, {
+ *   title: 'My Custom API Documentation',
+ *   includeToc: true,
+ *   includeSchemas: false,
+ * });
+ * ```
+ */
+export declare function generateMarkdownDocs(spec: OpenAPISpec, options?: MarkdownGeneratorOptions): string;
+//# sourceMappingURL=markdown-generator.d.ts.map

package/src/openapi/markdown-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-generator.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/openapi/markdown-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAA0C,MAAM,WAAW,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA0DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAqCR"}