@furystack/rest-service 12.2.0 → 12.3.0

package/esm/openapi/generate-openapi-document.spec.js

@@ -0,0 +1,643 @@
+import { describe, expect, it } from 'vitest';
+import { generateOpenApiDocument } from './generate-openapi-document.js';
+describe('generateOpenApiDocument', () => {
+    describe('Document structure', () => {
+        it('Should generate a valid OpenAPI 3.1 document', () => {
+            const api = {
+                GET: {
+                    '/test': { path: '/test', isAuthenticated: false, schemaName: 'Test', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.openapi).toBe('3.1.0');
+            expect(result.info.title).toBe('FuryStack API');
+            expect(result.info.version).toBe('1.0.0');
+            expect(result.info.description).toBe('API documentation generated from FuryStack API schema');
+            expect(result.jsonSchemaDialect).toBe('https://spec.openapis.org/oas/3.1/dialect/base');
+            expect(result.servers).toEqual([{ url: '/' }]);
+            expect(result.tags).toEqual([]);
+            expect(result.paths).toBeDefined();
+            expect(result.components).toBeDefined();
+        });
+        it('Should use custom title, description, and version', () => {
+            const result = generateOpenApiDocument({
+                api: {},
+                title: 'Custom API',
+                description: 'Custom description',
+                version: '3.0.0',
+            });
+            expect(result.info.title).toBe('Custom API');
+            expect(result.info.description).toBe('Custom description');
+            expect(result.info.version).toBe('3.0.0');
+        });
+        it('Should include cookieAuth security scheme', () => {
+            const result = generateOpenApiDocument({ api: {} });
+            expect(result.components?.securitySchemes?.cookieAuth).toEqual({
+                type: 'apiKey',
+                in: 'cookie',
+                name: 'session',
+            });
+        });
+    });
+    describe('HTTP methods', () => {
+        it('Should generate GET operations', () => {
+            const api = {
+                GET: { '/items': { path: '/items', isAuthenticated: false, schemaName: 'Items', schema: { type: 'array' } } },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.get).toBeDefined();
+        });
+        it('Should generate POST operations', () => {
+            const api = {
+                POST: { '/items': { path: '/items', isAuthenticated: false, schemaName: 'Item', schema: { type: 'object' } } },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.post).toBeDefined();
+        });
+        it('Should generate PUT operations', () => {
+            const api = {
+                PUT: {
+                    '/items/:id': {
+                        path: '/items/:id',
+                        isAuthenticated: false,
+                        schemaName: 'Item',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items/{id}']?.put).toBeDefined();
+        });
+        it('Should generate DELETE operations', () => {
+            const api = {
+                DELETE: {
+                    '/items/:id': {
+                        path: '/items/:id',
+                        isAuthenticated: false,
+                        schemaName: 'Item',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items/{id}']?.delete).toBeDefined();
+        });
+        it('Should generate PATCH operations', () => {
+            const api = {
+                PATCH: {
+                    '/items/:id': {
+                        path: '/items/:id',
+                        isAuthenticated: false,
+                        schemaName: 'Item',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items/{id}']?.patch).toBeDefined();
+        });
+        it('Should generate HEAD operations', () => {
+            const api = {
+                HEAD: { '/items': { path: '/items', isAuthenticated: false, schemaName: 'Items', schema: { type: 'object' } } },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.head).toBeDefined();
+        });
+        it('Should generate OPTIONS operations', () => {
+            const api = {
+                OPTIONS: {
+                    '/items': { path: '/items', isAuthenticated: false, schemaName: 'Items', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.options).toBeDefined();
+        });
+        it('Should generate TRACE operations', () => {
+            const api = {
+                TRACE: {
+                    '/items': { path: '/items', isAuthenticated: false, schemaName: 'Items', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.trace).toBeDefined();
+        });
+        it('Should handle multiple methods on the same path', () => {
+            const api = {
+                GET: {
+                    '/resource': {
+                        path: '/resource',
+                        isAuthenticated: false,
+                        schemaName: 'ResourceGet',
+                        schema: { type: 'object' },
+                    },
+                },
+                POST: {
+                    '/resource': {
+                        path: '/resource',
+                        isAuthenticated: true,
+                        schemaName: 'ResourcePost',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/resource']?.get).toBeDefined();
+            expect(result.paths?.['/resource']?.post).toBeDefined();
+        });
+    });
+    describe('Path parameters', () => {
+        it('Should convert :param to {param} in paths', () => {
+            const api = {
+                GET: {
+                    '/users/:id': {
+                        path: '/users/:id',
+                        isAuthenticated: false,
+                        schemaName: 'User',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/users/{id}']).toBeDefined();
+            expect(result.paths?.['/users/:id']).toBeUndefined();
+        });
+        it('Should generate path parameter objects', () => {
+            const api = {
+                GET: {
+                    '/users/:id': {
+                        path: '/users/:id',
+                        isAuthenticated: false,
+                        schemaName: 'User',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/users/{id}']?.get?.parameters;
+            expect(params).toHaveLength(1);
+            expect(params[0]).toEqual({
+                name: 'id',
+                in: 'path',
+                required: true,
+                description: 'Path parameter: id',
+                schema: { type: 'string' },
+            });
+        });
+        it('Should generate multiple path parameters', () => {
+            const api = {
+                GET: {
+                    '/users/:userId/posts/:postId': {
+                        path: '/users/:userId/posts/:postId',
+                        isAuthenticated: false,
+                        schemaName: 'Post',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/users/{userId}/posts/{postId}']?.get?.parameters;
+            expect(params).toHaveLength(2);
+            expect(params[0].name).toBe('userId');
+            expect(params[1].name).toBe('postId');
+        });
+    });
+    describe('Response schemas', () => {
+        it('Should reference schema via $ref when schemaName is set', () => {
+            const api = {
+                GET: {
+                    '/test': {
+                        path: '/test',
+                        isAuthenticated: false,
+                        schemaName: 'TestModel',
+                        schema: { type: 'object', properties: { id: { type: 'string' } } },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const response = result.paths?.['/test']?.get?.responses?.['200'];
+            expect((response.content?.['application/json']?.schema).$ref).toBe('#/components/schemas/TestModel');
+        });
+        it('Should include schemas in components', () => {
+            const testSchema = { type: 'object', properties: { id: { type: 'string' } } };
+            const api = {
+                GET: {
+                    '/test': { path: '/test', isAuthenticated: false, schemaName: 'TestModel', schema: testSchema },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.components?.schemas?.TestModel).toEqual(testSchema);
+        });
+        it('Should use generic object schema when no schemaName', () => {
+            const api = {
+                GET: {
+                    '/test': { path: '/test', isAuthenticated: false, schemaName: '', schema: null },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const response = result.paths?.['/test']?.get?.responses?.['200'];
+            expect(response.content?.['application/json']?.schema).toEqual({ type: 'object' });
+        });
+        it('Should include 401 and 500 error responses', () => {
+            const api = {
+                GET: {
+                    '/test': { path: '/test', isAuthenticated: false, schemaName: 'Test', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const responses = result.paths?.['/test']?.get?.responses;
+            expect(responses['401'].description).toBe('Unauthorized');
+            expect(responses['500'].description).toBe('Internal server error');
+        });
+        it('Should not add schema to components when schema is falsy', () => {
+            const api = {
+                GET: {
+                    '/test': { path: '/test', isAuthenticated: false, schemaName: 'Empty', schema: null },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.components?.schemas?.Empty).toBeUndefined();
+        });
+    });
+    describe('Request body extraction', () => {
+        it('Should include request body from schema definitions', () => {
+            const bodySchema = { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] };
+            const api = {
+                POST: {
+                    '/users': {
+                        path: '/users',
+                        isAuthenticated: false,
+                        schemaName: 'CreateUser',
+                        schema: {
+                            definitions: {
+                                CreateUser: {
+                                    type: 'object',
+                                    properties: { body: bodySchema, result: { type: 'object' } },
+                                    required: ['body', 'result'],
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const requestBody = result.paths?.['/users']?.post?.requestBody;
+            expect(requestBody).toBeDefined();
+            expect(requestBody.required).toBe(true);
+            expect(requestBody.content['application/json'].schema).toEqual(bodySchema);
+        });
+        it('Should mark request body as not required when body is optional in schema', () => {
+            const api = {
+                POST: {
+                    '/items': {
+                        path: '/items',
+                        isAuthenticated: false,
+                        schemaName: 'CreateItem',
+                        schema: {
+                            definitions: {
+                                CreateItem: {
+                                    type: 'object',
+                                    properties: { body: { type: 'object' }, result: { type: 'object' } },
+                                    required: ['result'],
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const requestBody = result.paths?.['/items']?.post?.requestBody;
+            expect(requestBody.required).toBe(false);
+        });
+        it('Should not add request body when schema has no body property', () => {
+            const api = {
+                GET: {
+                    '/items': {
+                        path: '/items',
+                        isAuthenticated: false,
+                        schemaName: 'ListItems',
+                        schema: {
+                            definitions: {
+                                ListItems: {
+                                    type: 'object',
+                                    properties: { result: { type: 'array' } },
+                                    required: ['result'],
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.get?.requestBody).toBeUndefined();
+        });
+        it('Should not add request body when schema has no definitions', () => {
+            const api = {
+                POST: {
+                    '/items': { path: '/items', isAuthenticated: false, schemaName: 'Item', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/items']?.post?.requestBody).toBeUndefined();
+        });
+    });
+    describe('Query parameter extraction', () => {
+        it('Should include query parameters from schema definitions', () => {
+            const api = {
+                GET: {
+                    '/search': {
+                        path: '/search',
+                        isAuthenticated: false,
+                        schemaName: 'Search',
+                        schema: {
+                            definitions: {
+                                Search: {
+                                    type: 'object',
+                                    properties: {
+                                        query: {
+                                            type: 'object',
+                                            properties: { q: { type: 'string' }, limit: { type: 'number' } },
+                                            required: ['q'],
+                                        },
+                                        result: { type: 'array' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/search']?.get?.parameters;
+            const queryParams = params.filter((p) => p.in === 'query');
+            expect(queryParams).toHaveLength(2);
+            expect(queryParams.find((p) => p.name === 'q')?.required).toBe(true);
+            expect(queryParams.find((p) => p.name === 'q')?.schema).toEqual({ type: 'string' });
+            expect(queryParams.find((p) => p.name === 'limit')?.required).toBe(false);
+            expect(queryParams.find((p) => p.name === 'limit')?.schema).toEqual({ type: 'number' });
+        });
+        it('Should not add query parameters when query has no properties', () => {
+            const api = {
+                GET: {
+                    '/items': {
+                        path: '/items',
+                        isAuthenticated: false,
+                        schemaName: 'Items',
+                        schema: {
+                            definitions: {
+                                Items: {
+                                    type: 'object',
+                                    properties: { query: { type: 'object' }, result: { type: 'array' } },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/items']?.get?.parameters;
+            expect(params.filter((p) => p.in === 'query')).toHaveLength(0);
+        });
+        it('Should mark query params as not required when required array is missing', () => {
+            const api = {
+                GET: {
+                    '/search': {
+                        path: '/search',
+                        isAuthenticated: false,
+                        schemaName: 'Search',
+                        schema: {
+                            definitions: {
+                                Search: {
+                                    type: 'object',
+                                    properties: {
+                                        query: {
+                                            type: 'object',
+                                            properties: { q: { type: 'string' } },
+                                        },
+                                        result: { type: 'array' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/search']?.get?.parameters;
+            const qParam = params.find((p) => p.in === 'query' && p.name === 'q');
+            expect(qParam?.required).toBe(false);
+        });
+    });
+    describe('Header parameter extraction', () => {
+        it('Should include header parameters from schema definitions', () => {
+            const api = {
+                GET: {
+                    '/data': {
+                        path: '/data',
+                        isAuthenticated: false,
+                        schemaName: 'GetData',
+                        schema: {
+                            definitions: {
+                                GetData: {
+                                    type: 'object',
+                                    properties: {
+                                        headers: {
+                                            type: 'object',
+                                            properties: { 'x-api-key': { type: 'string' } },
+                                            required: ['x-api-key'],
+                                        },
+                                        result: { type: 'object' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/data']?.get?.parameters;
+            const headerParams = params.filter((p) => p.in === 'header');
+            expect(headerParams).toHaveLength(1);
+            expect(headerParams[0].name).toBe('x-api-key');
+            expect(headerParams[0].required).toBe(true);
+            expect(headerParams[0].schema).toEqual({ type: 'string' });
+        });
+        it('Should not add header parameters when headers has no properties', () => {
+            const api = {
+                GET: {
+                    '/data': {
+                        path: '/data',
+                        isAuthenticated: false,
+                        schemaName: 'GetData',
+                        schema: {
+                            definitions: {
+                                GetData: {
+                                    type: 'object',
+                                    properties: { headers: { type: 'object' }, result: { type: 'object' } },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/data']?.get?.parameters;
+            expect(params.filter((p) => p.in === 'header')).toHaveLength(0);
+        });
+        it('Should mark header params as not required when required array is missing', () => {
+            const api = {
+                GET: {
+                    '/data': {
+                        path: '/data',
+                        isAuthenticated: false,
+                        schemaName: 'GetData',
+                        schema: {
+                            definitions: {
+                                GetData: {
+                                    type: 'object',
+                                    properties: {
+                                        headers: {
+                                            type: 'object',
+                                            properties: { 'x-token': { type: 'string' } },
+                                        },
+                                        result: { type: 'object' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            const params = result.paths?.['/data']?.get?.parameters;
+            const headerParam = params.find((p) => p.in === 'header' && p.name === 'x-token');
+            expect(headerParam?.required).toBe(false);
+        });
+    });
+    describe('Security', () => {
+        it('Should add cookieAuth for authenticated endpoints', () => {
+            const api = {
+                GET: {
+                    '/private': { path: '/private', isAuthenticated: true, schemaName: 'P', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/private']?.get?.security).toEqual([{ cookieAuth: [] }]);
+        });
+        it('Should use empty security for non-authenticated endpoints', () => {
+            const api = {
+                GET: {
+                    '/public': { path: '/public', isAuthenticated: false, schemaName: 'P', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/public']?.get?.security).toEqual([]);
+        });
+        it('Should use stored securitySchemes names when available', () => {
+            const api = {
+                GET: {
+                    '/private': {
+                        path: '/private',
+                        isAuthenticated: true,
+                        schemaName: 'P',
+                        schema: { type: 'object' },
+                        securitySchemes: ['bearerAuth'],
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/private']?.get?.security).toEqual([{ bearerAuth: [] }]);
+        });
+        it('Should use multiple stored securitySchemes names', () => {
+            const api = {
+                GET: {
+                    '/private': {
+                        path: '/private',
+                        isAuthenticated: true,
+                        schemaName: 'P',
+                        schema: { type: 'object' },
+                        securitySchemes: ['bearerAuth', 'apiKey'],
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/private']?.get?.security).toEqual([{ bearerAuth: [] }, { apiKey: [] }]);
+        });
+        it('Should use metadata securitySchemes keys as default when isAuthenticated is true', () => {
+            const api = {
+                GET: {
+                    '/private': { path: '/private', isAuthenticated: true, schemaName: 'P', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({
+                api,
+                metadata: {
+                    securitySchemes: {
+                        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+                        apiKey: { type: 'apiKey', in: 'header', name: 'X-API-Key' },
+                    },
+                },
+            });
+            expect(result.paths?.['/private']?.get?.security).toEqual([{ bearerAuth: [] }, { apiKey: [] }]);
+        });
+        it('Should prefer stored securitySchemes over metadata-derived defaults', () => {
+            const api = {
+                GET: {
+                    '/private': {
+                        path: '/private',
+                        isAuthenticated: true,
+                        schemaName: 'P',
+                        schema: { type: 'object' },
+                        securitySchemes: ['customScheme'],
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({
+                api,
+                metadata: {
+                    securitySchemes: {
+                        bearerAuth: { type: 'http', scheme: 'bearer' },
+                    },
+                },
+            });
+            expect(result.paths?.['/private']?.get?.security).toEqual([{ customScheme: [] }]);
+        });
+    });
+    describe('Operation metadata', () => {
+        it('Should generate operationId from method and path', () => {
+            const api = {
+                GET: {
+                    '/api/users/:id/profile': {
+                        path: '/api/users/:id/profile',
+                        isAuthenticated: false,
+                        schemaName: 'P',
+                        schema: { type: 'object' },
+                    },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/api/users/{id}/profile']?.get?.operationId).toBe('get_api_users_id_profile');
+        });
+        it('Should gracefully ignore unsupported HTTP methods like CONNECT', () => {
+            const api = {
+                CONNECT: {
+                    '/tunnel': { path: '/tunnel', isAuthenticated: false, schemaName: 'Tunnel', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/tunnel']).toBeDefined();
+            expect(result.paths?.['/tunnel']?.get).toBeUndefined();
+            expect(result.paths?.['/tunnel']?.post).toBeUndefined();
+        });
+        it('Should generate summary and description', () => {
+            const api = {
+                POST: {
+                    '/users': { path: '/users', isAuthenticated: false, schemaName: 'U', schema: { type: 'object' } },
+                },
+            };
+            const result = generateOpenApiDocument({ api });
+            expect(result.paths?.['/users']?.post?.summary).toBe('POST /users');
+            expect(result.paths?.['/users']?.post?.description).toBe('Endpoint for /users');
+        });
+    });
+});
+//# sourceMappingURL=generate-openapi-document.spec.js.map