@redocly/openapi-docs 3.24.0-next.9 → 3.24.1

package/lib/utils/__tests__/convertSwagger2OpenAPI.test.js

@@ -0,0 +1,392 @@
+import { vi } from 'vitest';
+import swagger2openapi from 'swagger2openapi';
+import { convertSwagger2OpenAPI } from '../convertSwagger2OpenAPI.js';
+// Mock the swagger2openapi module
+vi.mock('swagger2openapi');
+const mockSwagger2OpenAPI = swagger2openapi;
+describe('convertSwagger2OpenAPI', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('should convert a valid Swagger 2.0 spec to OpenAPI 3.0', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {
+                '/test': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'OK',
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {
+                '/test': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'OK',
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith(swaggerSpec, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+        expect(result).toEqual(expectedOpenAPISpec);
+    });
+    it('should add empty paths object if paths is missing', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+        };
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith({ ...swaggerSpec, paths: {} }, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+    });
+    it('should preserve existing paths if already present', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {
+                '/existing': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'OK',
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {
+                '/existing': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'OK',
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith(swaggerSpec, // Should not modify the original spec
+        { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+    });
+    it('should reject with error when swagger2openapi conversion fails', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        const conversionError = new Error('Invalid Swagger specification');
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(conversionError, null);
+            return undefined;
+        });
+        await expect(convertSwagger2OpenAPI(swaggerSpec)).rejects.toThrow('Invalid Swagger specification');
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith(swaggerSpec, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+    });
+    it('should handle swagger2openapi returning null result', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, null);
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(result).toBeUndefined();
+    });
+    it('should handle swagger2openapi returning result without openapi property', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { someOtherProperty: 'value' });
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(result).toBeUndefined();
+    });
+    it('should handle complex Swagger specification with all properties', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Complex API',
+                version: '2.0.0',
+                description: 'A complex API with many features',
+                contact: {
+                    name: 'API Support',
+                    email: 'support@example.com',
+                },
+                license: {
+                    name: 'MIT',
+                    url: 'https://opensource.org/licenses/MIT',
+                },
+            },
+            host: 'api.example.com',
+            basePath: '/v1',
+            schemes: ['https'],
+            consumes: ['application/json'],
+            produces: ['application/json'],
+            paths: {
+                '/users': {
+                    get: {
+                        tags: ['users'],
+                        summary: 'Get all users',
+                        description: 'Retrieve a list of all users',
+                        operationId: 'getUsers',
+                        parameters: [
+                            {
+                                name: 'limit',
+                                in: 'query',
+                                description: 'Number of users to return',
+                                required: false,
+                                type: 'integer',
+                                default: 10,
+                            },
+                        ],
+                        responses: {
+                            '200': {
+                                description: 'Successful response',
+                                schema: {
+                                    type: 'array',
+                                    items: {
+                                        $ref: '#/definitions/User',
+                                    },
+                                },
+                            },
+                            '400': {
+                                description: 'Bad request',
+                            },
+                        },
+                    },
+                },
+            },
+            definitions: {
+                User: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'integer',
+                            description: 'User ID',
+                        },
+                        name: {
+                            type: 'string',
+                            description: 'User name',
+                        },
+                    },
+                    required: ['id', 'name'],
+                },
+            },
+            securityDefinitions: {
+                apiKey: {
+                    type: 'apiKey',
+                    name: 'X-API-Key',
+                    in: 'header',
+                },
+            },
+        };
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'Complex API',
+                version: '2.0.0',
+                description: 'A complex API with many features',
+                contact: {
+                    name: 'API Support',
+                    email: 'support@example.com',
+                },
+                license: {
+                    name: 'MIT',
+                    url: 'https://opensource.org/licenses/MIT',
+                },
+            },
+            servers: [
+                {
+                    url: 'https://api.example.com/v1',
+                },
+            ],
+            paths: {
+                '/users': {
+                    get: {
+                        tags: ['users'],
+                        summary: 'Get all users',
+                        description: 'Retrieve a list of all users',
+                        operationId: 'getUsers',
+                        parameters: [
+                            {
+                                name: 'limit',
+                                in: 'query',
+                                description: 'Number of users to return',
+                                required: false,
+                                schema: {
+                                    type: 'integer',
+                                    default: 10,
+                                },
+                            },
+                        ],
+                        responses: {
+                            '200': {
+                                description: 'Successful response',
+                                content: {
+                                    'application/json': {
+                                        schema: {
+                                            type: 'array',
+                                            items: {
+                                                $ref: '#/components/schemas/User',
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                            '400': {
+                                description: 'Bad request',
+                            },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'integer',
+                                description: 'User ID',
+                            },
+                            name: {
+                                type: 'string',
+                                description: 'User name',
+                            },
+                        },
+                        required: ['id', 'name'],
+                    },
+                },
+                securitySchemes: {
+                    apiKey: {
+                        type: 'apiKey',
+                        name: 'X-API-Key',
+                        in: 'header',
+                        bearerFormat: '',
+                        flows: {},
+                    },
+                },
+            },
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith(swaggerSpec, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+        expect(result).toEqual(expectedOpenAPISpec);
+    });
+    it('should handle empty specification object', async () => {
+        const swaggerSpec = {};
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith({ paths: {} }, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+        expect(result).toEqual(expectedOpenAPISpec);
+    });
+    it('should handle specification with null paths', async () => {
+        const swaggerSpec = {
+            swagger: '2.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: null,
+        };
+        const expectedOpenAPISpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'Test API',
+                version: '1.0.0',
+            },
+            paths: {},
+        };
+        mockSwagger2OpenAPI.convertObj.mockImplementation((_spec, _options, callback) => {
+            callback(null, { openapi: expectedOpenAPISpec });
+            return undefined;
+        });
+        const result = await convertSwagger2OpenAPI(swaggerSpec);
+        expect(mockSwagger2OpenAPI.convertObj).toHaveBeenCalledWith({ ...swaggerSpec, paths: {} }, { patch: true, warnOnly: true, text: '{}', anchors: true }, expect.any(Function));
+        expect(result).toEqual(expectedOpenAPISpec);
+    });
+});
+//# sourceMappingURL=convertSwagger2OpenAPI.test.js.map

package/lib/utils/__tests__/debounce.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/__tests__/debounce.test.js

@@ -0,0 +1,54 @@
+import { debounce } from '../debounce.js';
+vi.useFakeTimers();
+describe('debounce', () => {
+    it('should debounce function calls', () => {
+        const fn = vi.fn();
+        const debouncedFn = debounce(fn, 100);
+        // Call the debounced function multiple times within the threshold
+        debouncedFn('a');
+        debouncedFn('b');
+        debouncedFn('c');
+        // Advance time by 99ms
+        vi.advanceTimersByTime(99);
+        // The function should not have been called yet
+        expect(fn).not.toHaveBeenCalled();
+        // Call the function again
+        debouncedFn('d');
+        // Advance time by another 99ms
+        vi.advanceTimersByTime(99);
+        // The function should still not have been called yet
+        expect(fn).not.toHaveBeenCalled();
+        // Advance time by the remaining 1ms
+        vi.advanceTimersByTime(1);
+        // The function should have been called once with the last value passed to it
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(fn).toHaveBeenCalledWith('d');
+    });
+    it('should call the function immediately when the `leading` option is `true`', () => {
+        const fn = vi.fn();
+        const debouncedFn = debounce(fn, 100, true);
+        // Call the debounced function multiple times within the threshold
+        debouncedFn('a');
+        debouncedFn('b');
+        debouncedFn('c');
+        // The function should have been called immediately with the first value passed to it
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(fn).toHaveBeenCalledWith('a');
+        // Advance time by 99ms
+        vi.advanceTimersByTime(99);
+        // The function should not have been called again yet
+        expect(fn).toHaveBeenCalledTimes(1);
+        // Call the function again
+        debouncedFn('d');
+        // Advance time by another 99ms
+        vi.advanceTimersByTime(99);
+        // The function should still not have been called yet
+        expect(fn).toHaveBeenCalledTimes(1);
+        // Advance time by the remaining 1ms
+        vi.advanceTimersByTime(1);
+        // The function should have been called once more with the last value passed to it
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(fn).toHaveBeenCalledWith('d');
+    });
+});
+//# sourceMappingURL=debounce.test.js.map

package/lib/utils/__tests__/debug.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/__tests__/debug.test.js

@@ -0,0 +1,23 @@
+import { debugTime } from '../debug.js';
+describe('debug', () => {
+    let spy;
+    beforeEach(() => {
+        spy = vi.spyOn(console, 'time');
+    });
+    afterEach(() => {
+        spy.mockRestore();
+    });
+    describe('debugTime', () => {
+        it('should call console.time with the given label in non-production environment', () => {
+            process.env.NODE_ENV = 'development';
+            debugTime('test');
+            expect(spy).toHaveBeenCalledWith('test');
+        });
+        it('should not call console.time in production environment', () => {
+            process.env.NODE_ENV = 'production';
+            debugTime('test');
+            expect(spy).not.toHaveBeenCalled();
+        });
+    });
+});
+//# sourceMappingURL=debug.test.js.map

package/lib/utils/__tests__/dom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/__tests__/dom.test.js

@@ -0,0 +1,108 @@
+import { querySelector, html2Str, IS_BROWSER } from '../dom.js';
+describe('DOM utils', () => {
+    describe('querySelector', () => {
+        afterEach(() => {
+            document.body.innerHTML = '';
+        });
+        it('should return element when document is defined', () => {
+            document.body.innerHTML = '<div></div>';
+            const div = querySelector('div');
+            expect(div).not.toBeNull();
+            expect(div?.tagName).toBe('DIV');
+        });
+        it('should return null for non-existent element', () => {
+            document.body.innerHTML = '<div></div>';
+            const span = querySelector('span');
+            expect(span).toBeNull();
+        });
+        it('should return null when document is undefined', () => {
+            expect(querySelector('div')).toBeNull();
+        });
+    });
+    describe('html2Str', () => {
+        it('should remove tags and keep text', () => {
+            expect(html2Str('<div><p>Hello</p> <span>World</span></div>')).toBe('Hello World');
+        });
+        it('should handle multiple spaces between chunks', () => {
+            expect(html2Str('<div> chunk1 </div> <div> chunk2 </div>')).toBe('chunk1 chunk2');
+        });
+        it('should return an empty string for empty input', () => {
+            expect(html2Str('')).toBe('');
+        });
+        it('should remove tags and newlines from HTML', () => {
+            expect(html2Str('<div>Hello\n<span>world</span></div>')).toBe('Hello world');
+        });
+        it('should return an empty string if input is empty', () => {
+            expect(html2Str('')).toBe('');
+        });
+    });
+    describe('IS_BROWSER', () => {
+        it('should be true in a browser-like environment', () => {
+            expect(IS_BROWSER).toBe(true);
+        });
+    });
+    describe('scrollIntoViewIfNeeded polyfill', () => {
+        let parent;
+        let child;
+        beforeEach(async () => {
+            parent = document.createElement('div');
+            child = document.createElement('div');
+            parent.appendChild(child);
+            document.body.appendChild(parent);
+            vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+                getPropertyValue: (prop) => {
+                    if (prop === 'border-top-width')
+                        return '10';
+                    if (prop === 'border-left-width')
+                        return '10';
+                    return '0';
+                },
+            });
+            Object.defineProperties(parent, {
+                offsetTop: { value: 100, configurable: true },
+                offsetLeft: { value: 100, configurable: true },
+                scrollTop: { value: 100, configurable: true, writable: true },
+                scrollLeft: { value: 100, configurable: true, writable: true },
+                clientHeight: { value: 200, configurable: true },
+                clientWidth: { value: 200, configurable: true },
+            });
+            Object.defineProperties(child, {
+                offsetTop: { value: 150, configurable: true },
+                offsetLeft: { value: 150, configurable: true },
+                clientHeight: { value: 50, configurable: true },
+                clientWidth: { value: 50, configurable: true },
+                scrollIntoView: { value: vi.fn(), configurable: true },
+            });
+            if (typeof Element.prototype.scrollIntoViewIfNeeded !== 'function') {
+                await import('../dom');
+            }
+        });
+        afterEach(() => {
+            if (parent.parentNode) {
+                parent.parentNode.removeChild(parent);
+            }
+            vi.restoreAllMocks();
+        });
+        it('should center the element when over top and centerIfNeeded is true', () => {
+            Object.defineProperty(child, 'offsetTop', { value: 50 });
+            child.scrollIntoViewIfNeeded(true);
+            expect(parent.scrollTop).toBe(-135);
+        });
+        it('should center the element when over bottom and centerIfNeeded is true', () => {
+            Object.defineProperty(child, 'offsetTop', { value: 350 });
+            child.scrollIntoViewIfNeeded(true);
+            expect(parent.scrollTop).toBe(100);
+        });
+        it('should scroll into view when over left and centerIfNeeded is false', () => {
+            Object.defineProperty(child, 'offsetLeft', { value: 50 });
+            child.scrollIntoViewIfNeeded(false);
+            expect(child.scrollIntoView).toHaveBeenCalled();
+        });
+        it('should scroll into view when over right and centerIfNeeded is false', () => {
+            Object.defineProperty(child, 'offsetLeft', { value: 350 });
+            child.scrollIntoViewIfNeeded(false);
+            expect(child.scrollIntoView).toHaveBeenCalled();
+        });
+    });
+});
+//# sourceMappingURL=dom.test.js.map

package/lib/utils/__tests__/getBreadcrumbs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/__tests__/getBreadcrumbs.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { getBreadcrumbs } from '../getBreadcrumbs.js';
+describe('getBreadcrumbs', () => {
+    it('should return empty array when tag has no parent', () => {
+        const tag = {
+            id: 'users-tag',
+            href: '/tags/users',
+            name: 'Users',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 1,
+        };
+        expect(getBreadcrumbs(tag)).toEqual([]);
+    });
+    it('should return single breadcrumb when tag has one parent', () => {
+        const parent = {
+            id: 'api-tag',
+            href: '/tag/api',
+            name: 'API',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 1,
+        };
+        const tag = {
+            id: 'users-tag',
+            href: '/tags/users',
+            name: 'Users',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 1,
+            parent,
+        };
+        expect(getBreadcrumbs(tag)).toEqual([
+            {
+                name: 'API',
+                href: '/tag/api',
+            },
+        ]);
+    });
+    it('should return empty array when provided element is not type "tag"', () => {
+        const tag = {
+            id: 'users-category',
+            href: '/category/users',
+            name: 'Users',
+            //@ts-ignore
+            type: 'category',
+            items: [],
+            depth: 0,
+            level: 1,
+        };
+        expect(getBreadcrumbs(tag)).toEqual([]);
+    });
+    it('should return breadcrumbs in correct order for multiple parents', () => {
+        const rootParent = {
+            id: 'root-tag',
+            href: '/tag/root',
+            name: 'Root',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 1,
+        };
+        const middleParent = {
+            id: 'api-tag',
+            href: '/tag/api',
+            name: 'API',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 2,
+            parent: rootParent,
+        };
+        const tag = {
+            id: 'users-tag',
+            href: '/tags/users',
+            name: 'Users',
+            type: 'tag',
+            items: [],
+            depth: 0,
+            level: 3,
+            parent: middleParent,
+        };
+        expect(getBreadcrumbs(tag)).toEqual([
+            {
+                name: 'Root',
+                href: '/tag/root',
+            },
+            {
+                name: 'API',
+                href: '/tag/api',
+            },
+        ]);
+    });
+});
+//# sourceMappingURL=getBreadcrumbs.test.js.map