@vida-global/core 2.0.11 → 2.1.0

package/test/server/openApi/apiDocsGenerator.test.js

@@ -0,0 +1,306 @@
+jest.mock('../../../lib/server/controllerImporter');
+jest.mock('../../../lib/server/openApi/schemaImporter');
+jest.mock('../../../lib/utils/yamlLoader');
+
+const   path                 = require('path');
+const { ControllerImporter } = require('../../../lib/server/controllerImporter');
+const { SchemaImporter }     = require('../../../lib/server/openApi/schemaImporter');
+const { YamlLoader }         = require('../../../lib/utils/yamlLoader');
+const { ApiDocsGenerator }   = require('../../../lib/server/openApi/apiDocsGenerator');
+const { StaticMethods }      = require('../../../lib/server/controllerMixins/renderer');
+
+
+const PACKAGE_FIXTURE_DIR = path.join(__dirname, 'helpers/apiDocsPackageFixture');
+
+
+const buildServer = (overrides = {}) => ({
+    controllerDirectories: ['/controllers'],
+    schemaDirectories:     [],
+    origin:                'https://localhost',
+    securitySchemes:       { apiKeyAuth: { type: 'apiKey', in: 'header', name: 'Authorization' } },
+    ...overrides,
+});
+
+
+const buildControllerClass = (overrides = {}) => ({
+    name:                         'ThingsController',
+    actions:                      [{ action: 'getIndex', method: 'GET', path: '/things' }],
+    parametersForAction:          () => ({ q: { isString: true } }),
+    _authenticationDocumentation: () => undefined,
+    _tagsDocumentation:           () => [],
+    documentationTagDefinitions:  () => [],
+    formatResponseBody:           StaticMethods.formatResponseBody,
+    formatErrors:                 StaticMethods.formatErrors,
+    ...overrides,
+});
+
+
+const mockControllerClasses = (classes) => {
+    ControllerImporter.mockImplementation(() => ({ controllerClasses: classes }));
+};
+
+
+beforeEach(() => {
+    jest.spyOn(process, 'cwd').mockReturnValue(PACKAGE_FIXTURE_DIR);
+    SchemaImporter.mockImplementation(() => ({ schemaClasses: new Map() }));
+    YamlLoader.fileExists.mockReturnValue(true);
+    YamlLoader.loadFile.mockReturnValue({ description: 'Lists things', summary: 'List things' });
+});
+afterEach(() => jest.resetAllMocks());
+
+
+describe('ApiDocsGenerator', () => {
+    describe('#specification', () => {
+        it ('returns a full OpenAPI 3.0 document with info, servers, paths and components', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer(), { title: 'Vida API', version: '2.1.0' });
+
+            expect(generator.specification).toEqual({
+                openapi: '3.0.0',
+                info:    { title: 'Vida API', version: '2.1.0', description: 'Fixture API description' },
+                servers: [{ url: 'https://localhost' }],
+                paths: {
+                    '/things': {
+                        get: {
+                            operationId: 'thingsGetIndex',
+                            summary:     'List things',
+                            description: 'Lists things',
+                            parameters:  [{ name: 'q', in: 'query', required: true, description: '', schema: { type: 'string' } }],
+                            responses:   { '200': { description: 'Successful response' } },
+                        },
+                    },
+                },
+                components: {
+                    securitySchemes: {
+                        apiKeyAuth: { type: 'apiKey', in: 'header', name: 'Authorization' },
+                    },
+                },
+            });
+        });
+
+        it ('uses the server origin for the servers url', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer({ origin: 'https://api.vida.inc' }));
+
+            expect(generator.specification.servers).toEqual([{ url: 'https://api.vida.inc' }]);
+        });
+
+        it ('falls back to package.json name, version and description when not provided', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.info).toEqual({
+                title:       'fixture-api',
+                version:     '9.9.9',
+                description: 'Fixture API description',
+            });
+        });
+
+        it ('prefers explicit title and version over package.json', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer(), { title: 'Explicit', version: '0.0.1' });
+
+            expect(generator.specification.info).toMatchObject({ title: 'Explicit', version: '0.0.1' });
+        });
+
+        it ('defaults info fields to empty strings when no package.json is found', () => {
+            process.cwd.mockReturnValue(__dirname);
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.info).toEqual({ title: '', version: '', description: '' });
+        });
+    });
+
+
+    describe('#paths', () => {
+        it ('nests each action documentation under its endpoint and lowercase method', () => {
+            const controllerClass = buildControllerClass({
+                actions: [
+                    { action: 'getIndex',  method: 'GET',  path: '/things' },
+                    { action: 'postIndex', method: 'POST', path: '/things' },
+                ],
+                parametersForAction: () => ({}),
+            });
+            YamlLoader.loadFile.mockReturnValue({ description: 'Documented' });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(Object.keys(generator.paths)).toEqual(['/things']);
+            expect(Object.keys(generator.paths['/things'])).toEqual(['get', 'post']);
+        });
+
+        it ('skips actions that have no documentation', () => {
+            const controllerClass = buildControllerClass({
+                actions: [{ action: 'getIndex', method: 'GET', path: '/things' }],
+            });
+            YamlLoader.loadFile.mockReturnValue({});
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.paths).toEqual({});
+        });
+
+        it ('aggregates paths across multiple controllers', () => {
+            const things = buildControllerClass({ parametersForAction: () => ({}) });
+            const users  = buildControllerClass({
+                actions:             [{ action: 'getIndex', method: 'GET', path: '/users' }],
+                parametersForAction: () => ({}),
+            });
+            mockControllerClasses([things, users]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(Object.keys(generator.paths).sort()).toEqual(['/things', '/users']);
+        });
+    });
+
+
+    describe('#components', () => {
+        it ('omits schemas when no controller references one', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.components.schemas).toBeUndefined();
+        });
+
+        it ('collects referenced schemas into components.schemas and emits a $ref', () => {
+            class Widget {
+                static documentationSchema() {
+                    return { id: { type: 'integer' } };
+                }
+            }
+            const controllerClass = buildControllerClass({
+                parametersForAction: () => ({ widget: { ref: Widget, queryParameter: true } }),
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+            const spec       = generator.specification;
+
+            expect(spec.components.schemas).toEqual({
+                Widget: { type: 'object', properties: { id: { type: 'integer' } } },
+            });
+            expect(spec.paths['/things'].get.parameters[0].schema).toEqual({ $ref: '#/components/schemas/Widget' });
+        });
+
+        it ('resolves a string ref via the schemaDirectories registry into components.schemas', () => {
+            class Widget {
+                static documentationSchema() { return { id: { type: 'integer' } }; }
+            }
+            SchemaImporter.mockImplementation(() => ({ schemaClasses: new Map([['Widget', Widget]]) }));
+            YamlLoader.loadFile.mockReturnValue({
+                description: 'Lists things',
+                responses:   { '200': { description: 'A widget', body: { ref: 'Widget' } } },
+            });
+            const controllerClass = buildControllerClass({
+                parametersForAction: () => ({}),
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+            const spec       = generator.specification;
+
+            expect(spec.components.schemas).toEqual({
+                Widget: { type: 'object', properties: { id: { type: 'integer' } } },
+            });
+            expect(spec.paths['/things'].get.responses['200'].content['application/json'].schema.properties.data)
+                .toEqual({ $ref: '#/components/schemas/Widget' });
+        });
+    });
+
+
+    describe('#tags', () => {
+        it ('aggregates a top-level tags list from a controller documentationTagDefinitions', () => {
+            const controllerClass = buildControllerClass({
+                _tagsDocumentation:          () => ['Things'],
+                documentationTagDefinitions: () => [{ name: 'Things', description: 'Thing endpoints' }],
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.tags).toEqual([{ name: 'Things', description: 'Thing endpoints' }]);
+        });
+
+        it ('omits the description key when the tag has no description', () => {
+            const controllerClass = buildControllerClass({
+                _tagsDocumentation:          () => ['Things'],
+                documentationTagDefinitions: () => [{ name: 'Things', description: '' }],
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.tags).toEqual([{ name: 'Things' }]);
+        });
+
+        it ('de-duplicates a tag used across multiple actions', () => {
+            const controllerClass = buildControllerClass({
+                actions: [
+                    { action: 'getIndex',  method: 'GET',  path: '/things' },
+                    { action: 'postIndex', method: 'POST', path: '/things' },
+                ],
+                parametersForAction:         () => ({}),
+                _tagsDocumentation:          () => ['Things'],
+                documentationTagDefinitions: () => [{ name: 'Things', description: 'Thing endpoints' }],
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.tags).toEqual([{ name: 'Things', description: 'Thing endpoints' }]);
+        });
+
+        it ('de-duplicates a tag shared across multiple controllers', () => {
+            const things = buildControllerClass({
+                parametersForAction:         () => ({}),
+                _tagsDocumentation:          () => ['Shared'],
+                documentationTagDefinitions: () => [{ name: 'Shared', description: '' }],
+            });
+            const users = buildControllerClass({
+                actions:                     [{ action: 'getIndex', method: 'GET', path: '/users' }],
+                parametersForAction:         () => ({}),
+                _tagsDocumentation:          () => ['Shared'],
+                documentationTagDefinitions: () => [{ name: 'Shared', description: '' }],
+            });
+            mockControllerClasses([things, users]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.tags).toEqual([{ name: 'Shared' }]);
+        });
+
+        it.each([
+            ['empty first', '', 'Has description'],
+            ['empty second', 'Has description', ''],
+        ])('keeps the first non-empty description when the same tag is declared twice (%s)', (_label, descA, descB) => {
+            const a = buildControllerClass({
+                parametersForAction:         () => ({}),
+                _tagsDocumentation:          () => ['Shared'],
+                documentationTagDefinitions: () => [{ name: 'Shared', description: descA }],
+            });
+            const b = buildControllerClass({
+                actions:                     [{ action: 'getIndex', method: 'GET', path: '/users' }],
+                parametersForAction:         () => ({}),
+                _tagsDocumentation:          () => ['Shared'],
+                documentationTagDefinitions: () => [{ name: 'Shared', description: descB }],
+            });
+            mockControllerClasses([a, b]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification.tags).toEqual([{ name: 'Shared', description: 'Has description' }]);
+        });
+
+        it ('omits the top-level tags key when no controller declares a tag', () => {
+            mockControllerClasses([buildControllerClass()]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(generator.specification).not.toHaveProperty('tags');
+        });
+
+        it ('places the tags key before paths in the document', () => {
+            const controllerClass = buildControllerClass({
+                _tagsDocumentation:          () => ['Things'],
+                documentationTagDefinitions: () => [{ name: 'Things', description: 'Thing endpoints' }],
+            });
+            mockControllerClasses([controllerClass]);
+            const generator = new ApiDocsGenerator(buildServer());
+
+            expect(Object.keys(generator.specification)).toEqual(['openapi', 'info', 'servers', 'tags', 'paths', 'components']);
+        });
+    });
+});

package/test/server/openApi/helpers/apiDocsPackageFixture/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "fixture-api",
+  "version": "9.9.9",
+  "description": "Fixture API description"
+}

package/test/server/openApi/schemaImporter.test.js

@@ -0,0 +1,54 @@
+const { SchemaImporter }       = require('../../../lib/server/openApi/schemaImporter');
+const { AbstractAutoImporter } = require('../../../lib/utils/abstractAutoImporter');
+
+
+afterEach(() => jest.restoreAllMocks());
+
+
+const withImports = (imports) => {
+    jest.spyOn(AbstractAutoImporter.prototype, 'imports', 'get').mockReturnValue(imports);
+    return new SchemaImporter([]);
+};
+
+
+describe('SchemaImporter', () => {
+    describe('#shouldImport', () => {
+        it ('returns true for a class exposing a static documentationSchema', () => {
+            class Widget { static documentationSchema() { return {}; } }
+            expect(new SchemaImporter([]).shouldImport(Widget)).toBe(true);
+        });
+
+
+        it ('returns false for a class without documentationSchema', () => {
+            class Bare {}
+            expect(new SchemaImporter([]).shouldImport(Bare)).toBe(false);
+        });
+    });
+
+
+    describe('#schemaClasses', () => {
+        it ('keys imported classes by their name', () => {
+            class Widget { static documentationSchema() {} }
+            const importer = withImports([Widget]);
+            expect(importer.schemaClasses.get('Widget')).toBe(Widget);
+        });
+
+
+        it ('keys classes by documentationSchemaName when provided', () => {
+            class Widget {
+                static documentationSchemaName = 'CustomWidget';
+                static documentationSchema()   {}
+            }
+            const importer = withImports([Widget]);
+            expect(importer.schemaClasses.get('CustomWidget')).toBe(Widget);
+        });
+
+
+        it ('throws when two classes resolve to the same name', () => {
+            class A { static documentationSchemaName = 'Dup'; static documentationSchema() {} }
+            class B { static documentationSchemaName = 'Dup'; static documentationSchema() {} }
+            const importer = withImports([A, B]);
+            expect(() => importer.schemaClasses).toThrow();
+        });
+    });
+});

package/test/server/openApi/schemaRegistry.test.js

@@ -0,0 +1,93 @@
+jest.mock('../../../lib/server/openApi/schemaImporter');
+
+const { SchemaImporter } = require('../../../lib/server/openApi/schemaImporter');
+const { SchemaRegistry } = require('../../../lib/server/openApi/schemaRegistry');
+const { Faker }          = require('@vida-global/test-helpers');
+
+
+const registryWith = (classes = new Map()) => {
+    SchemaImporter.mockImplementation(() => ({ schemaClasses: classes }));
+    return new SchemaRegistry({ schemaDirectories: [] });
+};
+
+
+afterEach(() => jest.resetAllMocks());
+
+
+describe('SchemaRegistry', () => {
+    describe('#has', () => {
+        it ('returns false for an unknown name', () => {
+            const registry = registryWith();
+            expect(registry.has(Faker.Text.randomString())).toBe(false);
+        });
+
+
+        it ('returns true after the name has been reserved', () => {
+            const registry = registryWith();
+            const name     = Faker.Text.randomString();
+            registry.reserve(name);
+            expect(registry.has(name)).toBe(true);
+        });
+
+
+        it ('returns true after the name has been set', () => {
+            const registry = registryWith();
+            const name     = Faker.Text.randomString();
+            registry.set(name, { type: 'object' });
+            expect(registry.has(name)).toBe(true);
+        });
+    });
+
+
+    describe('#reserve', () => {
+        it ('stores an empty placeholder so cycles can short-circuit', () => {
+            const registry = registryWith();
+            const name     = Faker.Text.randomString();
+            registry.reserve(name);
+            expect(registry.schemas[name]).toEqual({});
+        });
+    });
+
+
+    describe('#set', () => {
+        it ('replaces a reserved placeholder with the resolved schema', () => {
+            const registry = registryWith();
+            const name     = Faker.Text.randomString();
+            const schema   = { type: 'object', properties: { id: { type: 'integer' } } };
+            registry.reserve(name);
+            registry.set(name, schema);
+            expect(registry.schemas[name]).toEqual(schema);
+        });
+    });
+
+
+    describe('#resolve', () => {
+        it ('returns the class mapped to the name', () => {
+            class Widget {}
+            const name     = Faker.Text.randomString();
+            const registry = registryWith(new Map([[name, Widget]]));
+            expect(registry.resolve(name)).toBe(Widget);
+        });
+
+
+        it ('throws for an unknown name', () => {
+            const registry = registryWith();
+            expect(() => registry.resolve(Faker.Text.randomString())).toThrow();
+        });
+    });
+
+
+    describe('#schemas', () => {
+        it ('returns all stored schemas keyed by name', () => {
+            const registry = registryWith();
+            const nameA    = Faker.Text.randomString();
+            const nameB    = Faker.Text.randomString();
+            registry.set(nameA, { type: 'string' });
+            registry.set(nameB, { type: 'number' });
+            expect(registry.schemas).toEqual({
+                [nameA]: { type: 'string' },
+                [nameB]: { type: 'number' },
+            });
+        });
+    });
+});

package/test/server/openApi/schemas.test.js

@@ -0,0 +1,109 @@
+const { Schemas } = require('../../../lib/server/openApi/schemas');
+
+
+describe('Schemas', () => {
+    describe('.for', () => {
+        it.each([
+            ['isInteger',  { isInteger: { gte: 0, lte: 9 } }, { type: 'integer', minimum: 0, maximum: 9 }],
+            ['isNumber',   { isNumber: { gte: 1.5 } }, { type: 'number', minimum: 1.5 }],
+            ['isString',   { isString: { length: { gte: 2, lte: 8 }, regex: /^\d+$/ } }, { type: 'string', minLength: 2, maxLength: 8, pattern: '^\\d+$' }],
+            ['isBoolean',  { isBoolean: true }, { type: 'boolean' }],
+            ['isDateTime', { isDateTime: true }, { type: 'string', format: 'date-time' }],
+            ['isEnum',     { isEnum: { enums: ['a', 'b'] } }, { type: 'string', enum: ['a', 'b'] }],
+        ])('converts %s to the expected OpenAPI schema', (_label, details, expected) => {
+            expect(Schemas.for(details)).toEqual(expected);
+        });
+
+        it ('returns an empty schema for unrecognized details', () => {
+            expect(Schemas.for({ function: () => {} })).toEqual({});
+        });
+    });
+
+
+    describe('.schemaFor', () => {
+        it ('recurses into nested array items', () => {
+            const details = { isArray: { of: { isInteger: true } } };
+
+            expect(Schemas.schemaFor(details)).toEqual({ type: 'array', items: { type: 'integer' } });
+        });
+
+        it ('recurses into nested object properties and collects required names', () => {
+            const details = {
+                isObject: {
+                    properties: {
+                        city: { isString: true },
+                        zip:  { isString: true, optional: true },
+                    },
+                },
+            };
+
+            expect(Schemas.schemaFor(details)).toEqual({
+                type:       'object',
+                properties: { city: { type: 'string' }, zip: { type: 'string' } },
+                required:   ['city'],
+            });
+        });
+
+        it ('delegates ref nodes at any depth to the resolver', () => {
+            const details = {
+                isObject: {
+                    properties: {
+                        items: { isArray: { of: { ref: 'Widget' } } },
+                    },
+                },
+            };
+            const resolveRef = jest.fn(name => ({ $ref: `#/components/schemas/${name}` }));
+
+            expect(Schemas.schemaFor(details, resolveRef)).toEqual({
+                type:       'object',
+                properties: { items: { type: 'array', items: { $ref: '#/components/schemas/Widget' } } },
+                required:   ['items'],
+            });
+            expect(resolveRef).toHaveBeenCalledWith('Widget');
+        });
+
+        it ('ignores ref nodes when no resolver is provided', () => {
+            expect(Schemas.schemaFor({ isArray: { of: { ref: 'Widget' } } })).toEqual({
+                type:  'array',
+                items: {},
+            });
+        });
+    });
+
+
+    describe('.isRequired', () => {
+        it ('treats details without optional as required', () => {
+            expect(Schemas.isRequired({ isString: true })).toBe(true);
+        });
+
+        it ('treats optional:true as not required', () => {
+            expect(Schemas.isRequired({ isString: true, optional: true })).toBe(false);
+        });
+    });
+
+
+    describe('.objectSchema', () => {
+        it ('omits the required array when every property is optional', () => {
+            const schema = Schemas.objectSchema({
+                properties: { a: { isString: true, optional: true }, b: { isInteger: true, optional: true } },
+            });
+
+            expect(schema).toEqual({ type: 'object', properties: { a: { type: 'string' }, b: { type: 'integer' } } });
+            expect(schema).not.toHaveProperty('required');
+        });
+    });
+
+
+    describe('.booleanSchema', () => {
+        it ('returns the OpenAPI boolean schema', () => {
+            expect(Schemas.booleanSchema()).toEqual({ type: 'boolean' });
+        });
+    });
+
+
+    describe('.dateTimeSchema', () => {
+        it ('returns the OpenAPI date-time string schema', () => {
+            expect(Schemas.dateTimeSchema()).toEqual({ type: 'string', format: 'date-time' });
+        });
+    });
+});