mcp-openapi-schema-explorer 1.0.0

package/dist/src/rendering/path-item.d.ts

@@ -0,0 +1,45 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js';
+/**
+ * Wraps an OpenAPIV3.PathItemObject to make it renderable.
+ * Handles rendering the list of methods for a specific path and
+ * the details of specific operations (methods).
+ */
+export declare class RenderablePathItem implements RenderableSpecObject {
+    private pathItem;
+    private path;
+    private pathUriSuffix;
+    constructor(pathItem: OpenAPIV3.PathItemObject | undefined, path: string, // The raw, decoded path string e.g., "/users/{userId}"
+    pathUriSuffix: string);
+    /**
+     * Renders a token-efficient list of methods available for this path.
+     * Corresponds to the `openapi://paths/{path}` URI.
+     */
+    renderList(context: RenderContext): RenderResultItem[];
+    /**
+     * Renders the detail view for one or more specific operations (methods)
+     * Renders the detail view. For a PathItem, this usually means listing
+     * the methods, similar to renderList. The handler should call
+     * `renderOperationDetail` for specific method details.
+     */
+    renderDetail(context: RenderContext): RenderResultItem[];
+    /**
+     * Renders the detail view for one or more specific operations (methods)
+     * within this path item.
+     * Corresponds to the `openapi://paths/{path}/{method*}` URI.
+     * This is called by the handler after identifying the method(s).
+     *
+     * @param context - The rendering context.
+     * @param methods - Array of method names (e.g., ['get', 'post']).
+     * @returns An array of RenderResultItem representing the operation details.
+     */
+    renderOperationDetail(_context: RenderContext, // Context might be needed later
+    methods: string[]): RenderResultItem[];
+    /**
+     * Gets the OperationObject for a specific HTTP method within this path item.
+     * Performs case-insensitive lookup.
+     * @param method - The HTTP method string (e.g., 'get', 'POST').
+     * @returns The OperationObject or undefined if not found.
+     */
+    getOperation(method: string): OpenAPIV3.OperationObject | undefined;
+}

package/dist/src/rendering/path-item.js

@@ -0,0 +1,141 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { getOperationSummary, createErrorResult, generateListHint } from './utils.js'; // Add .js
+/**
+ * Wraps an OpenAPIV3.PathItemObject to make it renderable.
+ * Handles rendering the list of methods for a specific path and
+ * the details of specific operations (methods).
+ */
+export class RenderablePathItem {
+    constructor(pathItem, path, // The raw, decoded path string e.g., "/users/{userId}"
+    pathUriSuffix // Built using buildPathItemUriSuffix(path) e.g., 'paths/users%7BuserId%7D'
+    ) {
+        this.pathItem = pathItem;
+        this.path = path;
+        this.pathUriSuffix = pathUriSuffix;
+    }
+    /**
+     * Renders a token-efficient list of methods available for this path.
+     * Corresponds to the `openapi://paths/{path}` URI.
+     */
+    renderList(context) {
+        if (!this.pathItem) {
+            return createErrorResult(this.pathUriSuffix, 'Path item not found.');
+        }
+        // Correctly check if the lowercase key is one of the enum values
+        const methods = Object.keys(this.pathItem).filter(key => Object.values(OpenAPIV3.HttpMethods).includes(key.toLowerCase()));
+        // Check if methods array is empty *after* filtering
+        if (methods.length === 0) {
+            // Return a specific non-error message indicating no methods were found
+            return [
+                {
+                    uriSuffix: this.pathUriSuffix,
+                    data: `No standard HTTP methods found for path: ${decodeURIComponent(this.pathUriSuffix.substring('paths/'.length) // Get original path for display
+                    )}`,
+                    renderAsList: true,
+                    // isError is implicitly false here
+                },
+            ];
+        }
+        // Generate hint first using the new structure
+        const hint = generateListHint(context, {
+            itemType: 'pathMethod',
+            parentPath: this.path, // Use the stored raw path
+        });
+        // Hint includes leading newline, so start output with it directly
+        let outputLines = [hint.trim(), '']; // Trim leading newline from hint for first line
+        methods.sort().forEach(method => {
+            const operation = this.getOperation(method);
+            // Use summary or operationId (via getOperationSummary)
+            const summaryText = getOperationSummary(operation);
+            // Format as METHOD: Summary or just METHOD if no summary/opId
+            outputLines.push(`${method.toUpperCase()}${summaryText ? `: ${summaryText}` : ''}`);
+        });
+        return [
+            {
+                uriSuffix: this.pathUriSuffix,
+                data: outputLines.join('\n'), // Join lines into a single string
+                renderAsList: true,
+            },
+        ];
+    }
+    /**
+     * Renders the detail view for one or more specific operations (methods)
+     * Renders the detail view. For a PathItem, this usually means listing
+     * the methods, similar to renderList. The handler should call
+     * `renderOperationDetail` for specific method details.
+     */
+    renderDetail(context) {
+        // Delegate to renderList as the primary view for a path item itself.
+        return this.renderList(context);
+    }
+    /**
+     * Renders the detail view for one or more specific operations (methods)
+     * within this path item.
+     * Corresponds to the `openapi://paths/{path}/{method*}` URI.
+     * This is called by the handler after identifying the method(s).
+     *
+     * @param context - The rendering context.
+     * @param methods - Array of method names (e.g., ['get', 'post']).
+     * @returns An array of RenderResultItem representing the operation details.
+     */
+    renderOperationDetail(_context, // Context might be needed later
+    methods) {
+        if (!this.pathItem) {
+            // Create error results for all requested methods if path item is missing
+            return methods.map(method => ({
+                uriSuffix: `${this.pathUriSuffix}/${method}`,
+                data: null,
+                isError: true,
+                errorText: 'Path item not found.',
+                renderAsList: true,
+            }));
+        }
+        const results = [];
+        for (const method of methods) {
+            const operation = this.getOperation(method);
+            const operationUriSuffix = `${this.pathUriSuffix}/${method}`;
+            if (!operation) {
+                results.push({
+                    uriSuffix: operationUriSuffix,
+                    data: null,
+                    isError: true,
+                    errorText: `Method "${method.toUpperCase()}" not found for path.`,
+                    renderAsList: true,
+                });
+            }
+            else {
+                // Return the raw operation object; handler will format it
+                results.push({
+                    uriSuffix: operationUriSuffix,
+                    data: operation,
+                    // isError: false (default)
+                    // renderAsList: false (default)
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Gets the OperationObject for a specific HTTP method within this path item.
+     * Performs case-insensitive lookup.
+     * @param method - The HTTP method string (e.g., 'get', 'POST').
+     * @returns The OperationObject or undefined if not found.
+     */
+    getOperation(method) {
+        if (!this.pathItem) {
+            return undefined;
+        }
+        const lowerMethod = method.toLowerCase();
+        // Check if the key is a standard HTTP method defined in the enum
+        if (Object.values(OpenAPIV3.HttpMethods).includes(lowerMethod)) {
+            const operation = this.pathItem[lowerMethod];
+            // Basic check to ensure it looks like an operation object
+            if (typeof operation === 'object' && operation !== null && 'responses' in operation) {
+                // The check above narrows the type sufficiently, assertion is redundant
+                return operation;
+            }
+        }
+        return undefined; // Not a valid method or not an operation object
+    }
+}
+//# sourceMappingURL=path-item.js.map

package/dist/src/rendering/path-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-item.js","sourceRoot":"","sources":["../../../src/rendering/path-item.ts"],"names":[],"mappings":"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"}

package/dist/src/rendering/paths.d.ts

@@ -0,0 +1,26 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js';
+/**
+ * Wraps an OpenAPIV3.PathsObject to make it renderable.
+ * Handles rendering the list of all paths and methods.
+ */
+export declare class RenderablePaths implements RenderableSpecObject {
+    private paths;
+    constructor(paths: OpenAPIV3.PathsObject | undefined);
+    /**
+     * Renders a token-efficient list of all paths and their methods.
+     * Corresponds to the `openapi://paths` URI.
+     */
+    renderList(context: RenderContext): RenderResultItem[];
+    /**
+     * Renders the detail view. For the Paths object level, this isn't
+     * typically used directly. Details are requested per path or operation.
+     */
+    renderDetail(context: RenderContext): RenderResultItem[];
+    /**
+     * Gets the PathItemObject for a specific path.
+     * @param path - The decoded path string.
+     * @returns The PathItemObject or undefined if not found.
+     */
+    getPathItem(path: string): OpenAPIV3.PathItemObject | undefined;
+}

package/dist/src/rendering/paths.js

@@ -0,0 +1,78 @@
+import { OpenAPIV3 } from 'openapi-types';
+/**
+ * Wraps an OpenAPIV3.PathsObject to make it renderable.
+ * Handles rendering the list of all paths and methods.
+ */
+export class RenderablePaths {
+    constructor(paths) {
+        this.paths = paths;
+    }
+    /**
+     * Renders a token-efficient list of all paths and their methods.
+     * Corresponds to the `openapi://paths` URI.
+     */
+    renderList(context) {
+        if (!this.paths || Object.keys(this.paths).length === 0) {
+            return [
+                {
+                    uriSuffix: 'paths',
+                    data: 'No paths found in the specification.',
+                    renderAsList: true,
+                },
+            ];
+        }
+        // Generate hint first and prepend "Hint: "
+        const hintText = `Use '${context.baseUri}paths/{encoded_path}' to list methods for a specific path, or '${context.baseUri}paths/{encoded_path}/{method}' to view details for a specific operation.`;
+        let outputLines = [`Hint: ${hintText}`, '']; // Start with hint and a blank line
+        const pathEntries = Object.entries(this.paths).sort(([pathA], [pathB]) => pathA.localeCompare(pathB));
+        for (const [path, pathItem] of pathEntries) {
+            if (!pathItem)
+                continue;
+            // Create a list of valid, sorted, uppercase methods for the current path
+            const methods = [];
+            for (const key in pathItem) {
+                const lowerKey = key.toLowerCase();
+                if (Object.values(OpenAPIV3.HttpMethods).includes(lowerKey)) {
+                    // Check if it's a valid operation object before adding the method
+                    const operation = pathItem[key];
+                    if (typeof operation === 'object' && operation !== null && 'responses' in operation) {
+                        methods.push(lowerKey.toUpperCase());
+                    }
+                }
+            }
+            methods.sort(); // Sort methods alphabetically
+            // Format the line: METHODS /path
+            const methodsString = methods.length > 0 ? methods.join(' ') : '(No methods)';
+            outputLines.push(`${methodsString} ${path}`);
+        }
+        return [
+            {
+                uriSuffix: 'paths',
+                data: outputLines.join('\n'), // Join lines into a single string
+                renderAsList: true, // This result is always plain text
+            },
+        ];
+    }
+    /**
+     * Renders the detail view. For the Paths object level, this isn't
+     * typically used directly. Details are requested per path or operation.
+     */
+    renderDetail(context) {
+        // Delegate to renderList as the primary view for the collection of paths
+        return this.renderList(context);
+    }
+    /**
+     * Gets the PathItemObject for a specific path.
+     * @param path - The decoded path string.
+     * @returns The PathItemObject or undefined if not found.
+     */
+    getPathItem(path) {
+        // Use Map for safe access
+        if (!this.paths) {
+            return undefined;
+        }
+        const pathsMap = new Map(Object.entries(this.paths));
+        return pathsMap.get(path); // Map.get returns ValueType | undefined
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/rendering/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/rendering/paths.ts"],"names":[],"mappings":"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"}

package/dist/src/rendering/types.d.ts

@@ -0,0 +1,50 @@
+import { IFormatter } from '../services/formatters';
+/**
+ * Intermediate result structure returned by render methods.
+ * Contains the core data needed to build the final ResourceContent.
+ */
+export interface RenderResultItem {
+    /** The raw data object to be formatted. */
+    data: unknown;
+    /** The suffix to append to the base URI (e.g., 'info', 'paths/users', 'components/schemas/User'). */
+    uriSuffix: string;
+    /** Optional flag indicating an error for this specific item. */
+    isError?: boolean;
+    /** Optional error message if isError is true. */
+    errorText?: string;
+    /** Optional flag to indicate this should be rendered as a list (text/plain). */
+    renderAsList?: boolean;
+}
+/**
+ * Context required for rendering OpenAPI specification objects.
+ */
+export interface RenderContext {
+    /** Formatter instance for handling output (JSON/YAML). */
+    formatter: IFormatter;
+    /** Base URI for generating resource links (e.g., "openapi://"). */
+    baseUri: string;
+}
+/**
+ * Represents an OpenAPI specification object that can be rendered
+ * in different formats (list or detail).
+ */
+export interface RenderableSpecObject {
+    /**
+     * Generates data for a token-efficient list representation.
+     * @param context - The rendering context.
+     * @returns An array of RenderResultItem.
+     */
+    renderList(context: RenderContext): RenderResultItem[];
+    /**
+     * Generates data for a detailed representation.
+     * @param context - The rendering context.
+     * @returns An array of RenderResultItem.
+     */
+    renderDetail(context: RenderContext): RenderResultItem[];
+}
+/**
+ * Type guard to check if an object implements RenderableSpecObject.
+ * @param obj - The object to check.
+ * @returns True if the object implements RenderableSpecObject, false otherwise.
+ */
+export declare function isRenderableSpecObject(obj: unknown): obj is RenderableSpecObject;

package/dist/src/rendering/types.js

@@ -0,0 +1,12 @@
+/**
+ * Type guard to check if an object implements RenderableSpecObject.
+ * @param obj - The object to check.
+ * @returns True if the object implements RenderableSpecObject, false otherwise.
+ */
+export function isRenderableSpecObject(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        typeof obj.renderList === 'function' &&
+        typeof obj.renderDetail === 'function');
+}
+//# sourceMappingURL=types.js.map

package/dist/src/rendering/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rendering/types.ts"],"names":[],"mappings":"AAkDA;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAQ,GAA4B,CAAC,UAAU,KAAK,UAAU;QAC9D,OAAQ,GAA4B,CAAC,YAAY,KAAK,UAAU,CACjE,CAAC;AACJ,CAAC"}

package/dist/src/rendering/utils.d.ts

@@ -0,0 +1,31 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderContext, RenderResultItem } from './types.js';
+type ListItemType = 'componentType' | 'componentName' | 'pathMethod';
+interface HintContext {
+    itemType: ListItemType;
+    parentComponentType?: string;
+    parentPath?: string;
+}
+/**
+ * Safely retrieves the summary from an Operation object.
+ * Handles cases where the operation might be undefined or lack a summary.
+ *
+ * @param operation - The Operation object or undefined.
+ * @returns The operation summary or operationId string, truncated if necessary, or null if neither is available.
+ */
+export declare function getOperationSummary(operation: OpenAPIV3.OperationObject | undefined): string | null;
+/**
+ * Helper to generate a standard hint text for list views, using the centralized URI builders.
+ * @param renderContext - The rendering context containing the base URI.
+ * @param hintContext - Context about the type of items being listed and their parent context.
+ * @returns The hint string.
+ */
+export declare function generateListHint(renderContext: RenderContext, hintContext: HintContext): string;
+/**
+ * Helper to generate a standard error item for RenderResultItem arrays.
+ * @param uriSuffix - The URI suffix for the error context.
+ * @param message - The error message.
+ * @returns A RenderResultItem array containing the error.
+ */
+export declare function createErrorResult(uriSuffix: string, message: string): RenderResultItem[];
+export {};

package/dist/src/rendering/utils.js

@@ -0,0 +1,79 @@
+import { buildComponentDetailUriSuffix, buildComponentMapUriSuffix, buildOperationUriSuffix,
+// buildPathItemUriSuffix, // Not currently used by generateListHint
+ } from '../utils/uri-builder.js'; // Added .js extension
+/**
+ * Safely retrieves the summary from an Operation object.
+ * Handles cases where the operation might be undefined or lack a summary.
+ *
+ * @param operation - The Operation object or undefined.
+ * @returns The operation summary or operationId string, truncated if necessary, or null if neither is available.
+ */
+export function getOperationSummary(operation) {
+    // Return summary or operationId without truncation
+    return operation?.summary || operation?.operationId || null;
+}
+/**
+ * Helper to generate a standard hint text for list views, using the centralized URI builders.
+ * @param renderContext - The rendering context containing the base URI.
+ * @param hintContext - Context about the type of items being listed and their parent context.
+ * @returns The hint string.
+ */
+export function generateListHint(renderContext, hintContext) {
+    let detailUriSuffixPattern;
+    let itemTypeName; // User-friendly name for the item type in the hint text
+    switch (hintContext.itemType) {
+        case 'componentType':
+            // Listing component types (e.g., schemas, responses) at openapi://components
+            // Hint should point to openapi://components/{type}
+            detailUriSuffixPattern = buildComponentMapUriSuffix('{type}'); // Use placeholder
+            itemTypeName = 'component type';
+            break;
+        case 'componentName':
+            // Listing component names (e.g., MySchema, User) at openapi://components/{type}
+            // Hint should point to openapi://components/{type}/{name}
+            if (!hintContext.parentComponentType) {
+                console.warn('generateListHint called for componentName without parentComponentType');
+                return ''; // Avoid generating a broken hint
+            }
+            // Use the actual parent type and a placeholder for the name
+            detailUriSuffixPattern = buildComponentDetailUriSuffix(hintContext.parentComponentType, '{name}');
+            itemTypeName = hintContext.parentComponentType.slice(0, -1); // e.g., 'schema' from 'schemas'
+            break;
+        case 'pathMethod':
+            // Listing methods (e.g., get, post) at openapi://paths/{path}
+            // Hint should point to openapi://paths/{path}/{method}
+            if (!hintContext.parentPath) {
+                console.warn('generateListHint called for pathMethod without parentPath');
+                return ''; // Avoid generating a broken hint
+            }
+            // Use the actual parent path and a placeholder for the method
+            detailUriSuffixPattern = buildOperationUriSuffix(hintContext.parentPath, '{method}');
+            itemTypeName = 'operation'; // Or 'method'? 'operation' seems clearer
+            break;
+        default:
+            // Explicitly cast to string to avoid potential 'never' type issue in template literal
+            console.warn(`Unknown itemType in generateListHint: ${String(hintContext.itemType)}`);
+            return ''; // Avoid generating a hint if context is unknown
+    }
+    // Construct the full hint URI pattern using the base URI
+    const fullHintPattern = `${renderContext.baseUri}${detailUriSuffixPattern}`;
+    return `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+}
+/**
+ * Helper to generate a standard error item for RenderResultItem arrays.
+ * @param uriSuffix - The URI suffix for the error context.
+ * @param message - The error message.
+ * @returns A RenderResultItem array containing the error.
+ */
+export function createErrorResult(uriSuffix, message) {
+    return [
+        {
+            uriSuffix: uriSuffix,
+            data: null,
+            isError: true,
+            errorText: message,
+            renderAsList: true, // Errors are typically plain text
+        },
+    ];
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/rendering/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/rendering/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB;AACvB,oEAAoE;EACrE,MAAM,yBAAyB,CAAC,CAAC,sBAAsB;AAcxD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAgD;IAEhD,mDAAmD;IACnD,OAAO,SAAS,EAAE,OAAO,IAAI,SAAS,EAAE,WAAW,IAAI,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAA4B,EAAE,WAAwB;IACrF,IAAI,sBAA8B,CAAC;IACnC,IAAI,YAAoB,CAAC,CAAC,wDAAwD;IAElF,QAAQ,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC7B,KAAK,eAAe;YAClB,6EAA6E;YAC7E,mDAAmD;YACnD,sBAAsB,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB;YACjF,YAAY,GAAG,gBAAgB,CAAC;YAChC,MAAM;QACR,KAAK,eAAe;YAClB,gFAAgF;YAChF,0DAA0D;YAC1D,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;gBACrC,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;gBACtF,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,4DAA4D;YAC5D,sBAAsB,GAAG,6BAA6B,CACpD,WAAW,CAAC,mBAAmB,EAC/B,QAAQ,CACT,CAAC;YACF,YAAY,GAAG,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,gCAAgC;YAC7F,MAAM;QACR,KAAK,YAAY;YACf,8DAA8D;YAC9D,uDAAuD;YACvD,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;gBAC1E,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,8DAA8D;YAC9D,sBAAsB,GAAG,uBAAuB,CAAC,WAAW,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACrF,YAAY,GAAG,WAAW,CAAC,CAAC,yCAAyC;YACrE,MAAM;QACR;YACE,sFAAsF;YACtF,OAAO,CAAC,IAAI,CAAC,yCAAyC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACtF,OAAO,EAAE,CAAC,CAAC,gDAAgD;IAC/D,CAAC;IAED,yDAAyD;IACzD,MAAM,eAAe,GAAG,GAAG,aAAa,CAAC,OAAO,GAAG,sBAAsB,EAAE,CAAC;IAE5E,OAAO,gBAAgB,eAAe,oCAAoC,YAAY,GAAG,CAAC;AAC5F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,OAAe;IAClE,OAAO;QACL;YACE,SAAS,EAAE,SAAS;YACpB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,OAAO;YAClB,YAAY,EAAE,IAAI,EAAE,kCAAkC;SACvD;KACF,CAAC;AACJ,CAAC"}

package/dist/src/services/formatters.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Supported output formats
+ */
+export type OutputFormat = 'json' | 'yaml' | 'json-minified';
+/**
+ * Interface for formatters that handle different output formats
+ */
+export interface IFormatter {
+    format(data: unknown): string;
+    getMimeType(): string;
+}
+/**
+ * JSON formatter with pretty printing
+ */
+export declare class JsonFormatter implements IFormatter {
+    format(data: unknown): string;
+    getMimeType(): string;
+}
+/**
+ * Formats data as minified JSON.
+ */
+export declare class MinifiedJsonFormatter implements IFormatter {
+    format(data: unknown): string;
+    getMimeType(): string;
+}
+/**
+ * YAML formatter using js-yaml library
+ */
+export declare class YamlFormatter implements IFormatter {
+    format(data: unknown): string;
+    getMimeType(): string;
+}
+/**
+ * Creates a formatter instance based on format name
+ */
+export declare function createFormatter(format: OutputFormat): IFormatter;

package/dist/src/services/formatters.js

@@ -0,0 +1,52 @@
+import { dump as yamlDump } from 'js-yaml';
+/**
+ * JSON formatter with pretty printing
+ */
+export class JsonFormatter {
+    format(data) {
+        return JSON.stringify(data, null, 2);
+    }
+    getMimeType() {
+        return 'application/json';
+    }
+}
+/**
+ * Formats data as minified JSON.
+ */
+export class MinifiedJsonFormatter {
+    format(data) {
+        return JSON.stringify(data);
+    }
+    getMimeType() {
+        return 'application/json';
+    }
+}
+/**
+ * YAML formatter using js-yaml library
+ */
+export class YamlFormatter {
+    format(data) {
+        return yamlDump(data, {
+            indent: 2,
+            lineWidth: -1, // Don't wrap long lines
+            noRefs: true, // Don't use references
+        });
+    }
+    getMimeType() {
+        return 'text/yaml';
+    }
+}
+/**
+ * Creates a formatter instance based on format name
+ */
+export function createFormatter(format) {
+    switch (format) {
+        case 'json':
+            return new JsonFormatter();
+        case 'yaml':
+            return new YamlFormatter();
+        case 'json-minified':
+            return new MinifiedJsonFormatter();
+    }
+}
+//# sourceMappingURL=formatters.js.map

package/dist/src/services/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../../../src/services/formatters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,SAAS,CAAC;AAe3C;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB,MAAM,CAAC,IAAa;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,WAAW;QACT,OAAO,kBAAkB,CAAC;IAC5B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAqB;IAChC,MAAM,CAAC,IAAa;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,WAAW;QACT,OAAO,kBAAkB,CAAC;IAC5B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB,MAAM,CAAC,IAAa;QAClB,OAAO,QAAQ,CAAC,IAAI,EAAE;YACpB,MAAM,EAAE,CAAC;YACT,SAAS,EAAE,CAAC,CAAC,EAAE,wBAAwB;YACvC,MAAM,EAAE,IAAI,EAAE,uBAAuB;SACtC,CAAC,CAAC;IACL,CAAC;IAED,WAAW;QACT,OAAO,WAAW,CAAC;IACrB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,IAAI,aAAa,EAAE,CAAC;QAC7B,KAAK,MAAM;YACT,OAAO,IAAI,aAAa,EAAE,CAAC;QAC7B,KAAK,eAAe;YAClB,OAAO,IAAI,qBAAqB,EAAE,CAAC;IACvC,CAAC;AACH,CAAC"}

package/dist/src/services/reference-transform.d.ts

@@ -0,0 +1,27 @@
+import { OpenAPIV3 } from 'openapi-types';
+export interface TransformContext {
+    resourceType: 'endpoint' | 'schema';
+    format: 'openapi' | 'asyncapi' | 'graphql';
+    path?: string;
+    method?: string;
+}
+export interface ReferenceObject {
+    $ref: string;
+}
+export interface TransformedReference {
+    $ref: string;
+}
+export interface ReferenceTransform<T> {
+    transformRefs(document: T, context: TransformContext): T;
+}
+export declare class ReferenceTransformService {
+    private transformers;
+    registerTransformer<T>(format: string, transformer: ReferenceTransform<T>): void;
+    transformDocument<T>(document: T, context: TransformContext): T;
+}
+export declare class OpenAPITransformer implements ReferenceTransform<OpenAPIV3.Document> {
+    private transformObject;
+    private isReferenceObject;
+    private transformReference;
+    transformRefs(document: OpenAPIV3.Document, context: TransformContext): OpenAPIV3.Document;
+}