@vida-global/core 2.0.10 → 2.1.0

package/test/server/apiDocGenerator.test.js

@@ -0,0 +1,743 @@
+jest.mock('../../lib/server/openApi/schemaImporter');
+jest.mock('../../lib/utils/yamlLoader');
+
+const { ApiDocGenerator } = require('../../lib/server/openApi/apiDocGenerator');
+const { SchemaRegistry }  = require('../../lib/server/openApi/schemaRegistry');
+const { SchemaImporter }  = require('../../lib/server/openApi/schemaImporter');
+const { YamlLoader }      = require('../../lib/utils/yamlLoader');
+const { StaticMethods }   = require('../../lib/server/controllerMixins/renderer');
+const { Faker }           = require('@vida-global/test-helpers');
+
+
+const ControllerClass = {
+    name:                         'ThingsController',
+    parametersForAction:          jest.fn(),
+    _authenticationDocumentation: jest.fn(),
+    _tagsDocumentation:           jest.fn(),
+    formatResponseBody:           StaticMethods.formatResponseBody,
+    formatErrors:                 StaticMethods.formatErrors,
+};
+const V2ControllerClass = {
+    name:                         'ThingsController',
+    parametersForAction:          jest.fn(),
+    _authenticationDocumentation: jest.fn(),
+    _tagsDocumentation:           jest.fn(),
+    formatErrors:                 StaticMethods.formatErrors,
+    formatResponseBody(body, errors, { statusCode, statusText }) {
+        const response = { success: statusCode < 400 };
+        if (!response.success) {
+            response.message = errors?.message || statusText;
+            if (errors && errors.fields) response.errors = errors.fields;
+        }
+        if (body && typeof body === 'object') Object.assign(response, body);
+        return response;
+    },
+};
+const shuffle = (arr) => arr.sort(() => Math.random() - 0.5);
+
+
+beforeEach(() => {
+    SchemaImporter.mockImplementation(() => ({ schemaClasses: new Map() }));
+    YamlLoader.fileExists.mockReturnValue(true);
+    YamlLoader.loadFile.mockReturnValue({});
+});
+afterEach(() => jest.resetAllMocks());
+
+
+describe('ApiDocGenerator', () => {
+    const toExpressUrl   = (pcs, params) => '/' + pcs.map(pc => params.includes(pc) ? `:${pc}` : pc).join('/');
+    const toFormattedUrl = (pcs, params) => '/' + pcs.map(pc => params.includes(pc) ? `{${pc}}` : pc).join('/');
+    describe('#endpoint', () => {
+        it ('replaces a single :param with {param}', () => {
+            const pcs          = [Faker.Text.randomString()];
+            const params       = [Faker.Text.randomString()];
+            const pathElements = shuffle([...pcs, ...params])
+            const path         = toExpressUrl(pathElements, params);
+            const formattedUrl = toFormattedUrl(pathElements, params);
+            const action       = { path };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.endpoint).toEqual(formattedUrl);
+        });
+
+        it ('replaces multiple :params with {params}', () => {
+            const pcs          = [Faker.Text.randomString(), Faker.Text.randomString()];
+            const params       = [Faker.Text.randomString(), Faker.Text.randomString()];
+            const pathElements = shuffle([...pcs, ...params])
+            const path         = toExpressUrl(pathElements, params);
+            const formattedUrl = toFormattedUrl(pathElements, params);
+            const action       = { path };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.endpoint).toEqual(formattedUrl);
+        });
+
+        it ('returns the path unchanged when there are no params', () => {
+            const path      = `/${Faker.Text.randomString()}/${Faker.Text.randomString()}`;
+            const action    = { path };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.endpoint).toEqual(path);
+        });
+
+        it ('handles an empty path', () => {
+            const path      = '';
+            const action    = { path };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.endpoint).toEqual('');
+        });
+    });
+
+
+    describe('#hasDocumentation', () => {
+        const action = { action: 'getIndex', method: 'GET', path: '/things' };
+
+        it ('returns true when the documentation has a description', () => {
+            YamlLoader.loadFile.mockReturnValue({ description: Faker.Text.randomString() });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.hasDocumentation).toBe(true);
+        });
+
+        it ('returns false when the documentation sets skip to true', () => {
+            YamlLoader.loadFile.mockReturnValue({ description: Faker.Text.randomString(), skip: true });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.hasDocumentation).toBe(false);
+        });
+
+        it ('ignores a non-true skip value', () => {
+            YamlLoader.loadFile.mockReturnValue({ description: Faker.Text.randomString(), skip: 'yes' });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+            expect(generator.hasDocumentation).toBe(true);
+        });
+    });
+
+
+    describe('#pathParams', () => {
+        it ('builds an OpenAPI path parameter object from the path param definition', () => {
+            const action = { action: 'getRecord', method: 'GET', path: '/user/:id' };
+            ControllerClass.parametersForAction.mockReturnValue({ id: { isInteger: { gte: 1 } } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.pathParams).toEqual({
+                id: {
+                    name:        'id',
+                    in:          'path',
+                    required:    true,
+                    description: '',
+                    schema:      { type: 'integer', minimum: 1 },
+                },
+            });
+        });
+
+        it ('marks path params required even when the definition is optional', () => {
+            const action = { action: 'getRecord', method: 'GET', path: '/user/:id' };
+            ControllerClass.parametersForAction.mockReturnValue({ id: { isString: true, optional: true } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.pathParams.id.required).toBe(true);
+        });
+
+        it ('excludes parameters that are not in the path', () => {
+            const action = { action: 'getRecord', method: 'GET', path: '/user/:id' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                id:    { isInteger: true },
+                other: { isString: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(Object.keys(generator.pathParams)).toEqual(['id']);
+        });
+    });
+
+
+    describe('#queryParams', () => {
+        it ('builds OpenAPI query parameter objects for a GET action', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                q:    { isString: true },
+                page: { isInteger: { gte: 1 }, optional: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams).toEqual({
+                q: {
+                    name: 'q', in: 'query', required: true, description: '',
+                    schema: { type: 'string' },
+                },
+                page: {
+                    name: 'page', in: 'query', required: false, description: '',
+                    schema: { type: 'integer', minimum: 1 },
+                },
+            });
+        });
+
+        it ('includes params flagged queryParameter on a POST and excludes the rest', () => {
+            const action = { action: 'postIndex', method: 'POST', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                baz:  { isInteger: { gte: 0 }, queryParameter: true },
+                body: { isString: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(Object.keys(generator.queryParams)).toEqual(['baz']);
+            expect(generator.queryParams.baz.in).toEqual('query');
+        });
+
+        it ('excludes path params from the query', () => {
+            const action = { action: 'getRecordStatus', method: 'GET', path: '/user/:id/status' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                id:     { isInteger: true },
+                detail: { isString: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(Object.keys(generator.queryParams)).toEqual(['detail']);
+        });
+    });
+
+
+    describe('#bodyProperties', () => {
+        it ('builds JSON Schema properties for a POST body and passes through example', () => {
+            const action = { action: 'postIndex', method: 'POST', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                foo: { isString: { length: { gte: 4, lte: 50 } }, example: 'Mark Grayson' },
+                bar: { isInteger: { gte: 0 } },
+                opt: { isString: true, optional: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.bodyProperties).toEqual({
+                foo: { type: 'string', minLength: 4, maxLength: 50, example: 'Mark Grayson', description: '' },
+                bar: { type: 'integer', minimum: 0, description: '' },
+                opt: { type: 'string', description: '' },
+            });
+        });
+
+        it ('excludes path params and is empty for a GET action', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ q: { isString: true } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.bodyProperties).toEqual({});
+        });
+    });
+
+
+    describe('schema mapping', () => {
+        const cases = [
+            ['isInteger with bounds', { isInteger: { gte: 0, lte: 9 } }, { type: 'integer', minimum: 0, maximum: 9 }],
+            ['isString with length',  { isString: { length: { gte: 2, lte: 8 } } }, { type: 'string', minLength: 2, maxLength: 8 }],
+            ['isString with regex',   { isString: { regex: /^\d+$/ } }, { type: 'string', 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'] }],
+            ['isNumber with bounds',  { isNumber: { gte: 0, lte: 9.99 } }, { type: 'number', minimum: 0, maximum: 9.99 }],
+            ['numeric isEnum',        { isEnum: { enums: [1, 2] } }, { type: 'integer', enum: [1, 2] }],
+            ['float isEnum',          { isEnum: { enums: [1.5, 2] } }, { type: 'number', enum: [1.5, 2] }],
+            ['isArray with items',    { isArray: { of: { isInteger: { gte: 1 } }, length: { gte: 1, lte: 5 } } }, { type: 'array', items: { type: 'integer', minimum: 1 }, minItems: 1, maxItems: 5 }],
+            ['isObject with props',   { isObject: { properties: { city: { isString: true }, zip: { isString: true, optional: true } } } }, { type: 'object', properties: { city: { type: 'string' }, zip: { type: 'string' } }, required: ['city'] }],
+            ['function only',         { function: () => {} }, {}],
+        ];
+
+        it.each(cases)('maps %s to the expected schema', (_label, definition, expectedSchema) => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ field: definition });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams.field.schema).toEqual(expectedSchema);
+        });
+    });
+
+
+    describe('ref schemas', () => {
+        const buildRefGenerator = (refClass, registry) => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ field: { ref: refClass } });
+            return new ApiDocGenerator(action, ControllerClass, registry);
+        };
+
+        it ('emits a $ref pointing at the component name', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            const generator = buildRefGenerator(Widget, new SchemaRegistry());
+
+            expect(generator.queryParams.field.schema).toEqual({ $ref: '#/components/schemas/Widget' });
+        });
+
+        it ('registers the resolved schema once under the class name', () => {
+            class Widget {
+                static documentationSchema() {
+                    return { id: { type: 'integer' } };
+                }
+            }
+            const registry  = new SchemaRegistry();
+            const generator = buildRefGenerator(Widget, registry);
+
+            generator.queryParams;
+            expect(registry.schemas).toEqual({
+                Widget: { type: 'object', properties: { id: { type: 'integer' } } },
+            });
+        });
+
+        it ('uses documentationSchemaName as the component key when provided', () => {
+            class Widget {
+                static documentationSchemaName = 'CustomWidget';
+                static documentationSchema()   { return { name: { type: 'string' } }; }
+            }
+            const registry  = new SchemaRegistry();
+            const generator = buildRefGenerator(Widget, registry);
+
+            expect(generator.queryParams.field.schema).toEqual({ $ref: '#/components/schemas/CustomWidget' });
+            expect(registry.schemas.CustomWidget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('registers a schema containing a literal self $ref as provided', () => {
+            class Node {
+                static documentationSchema() {
+                    return { next: { $ref: '#/components/schemas/Node' } };
+                }
+            }
+            const registry  = new SchemaRegistry();
+            const generator = buildRefGenerator(Node, registry);
+
+            expect(generator.queryParams.field.schema).toEqual({ $ref: '#/components/schemas/Node' });
+            expect(registry.schemas).toEqual({
+                Node: { type: 'object', properties: { next: { $ref: '#/components/schemas/Node' } } },
+            });
+        });
+
+        it ('throws when the ref target has no documentationSchema method', () => {
+            class Bare {}
+            const generator = buildRefGenerator(Bare, new SchemaRegistry());
+
+            expect(() => generator.queryParams).toThrow();
+        });
+
+        it ('throws a descriptive error when a live-class ref is null', () => {
+            const generator = buildRefGenerator(null, new SchemaRegistry());
+
+            expect(() => generator.queryParams).toThrow('A ref target must expose a static documentationSchema() method');
+        });
+
+        it ('resolves a string ref against the registry class map', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            SchemaImporter.mockImplementation(() => ({ schemaClasses: new Map([['Widget', Widget]]) }));
+            const registry  = new SchemaRegistry({ schemaDirectories: [] });
+            const generator = buildRefGenerator('Widget', registry);
+
+            expect(generator.queryParams.field.schema).toEqual({ $ref: '#/components/schemas/Widget' });
+            expect(registry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('throws when a string ref is not in the registry', () => {
+            const generator = buildRefGenerator('Missing', new SchemaRegistry());
+
+            expect(() => generator.queryParams).toThrow();
+        });
+
+        it ('resolves a ref nested inside array items', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ field: { isArray: { of: { ref: Widget } } } });
+            const registry  = new SchemaRegistry();
+            const generator = new ApiDocGenerator(action, ControllerClass, registry);
+
+            expect(generator.queryParams.field.schema).toEqual({
+                type:  'array',
+                items: { $ref: '#/components/schemas/Widget' },
+            });
+            expect(registry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('resolves a ref nested inside object properties', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                field: { isObject: { properties: { widget: { ref: Widget }, count: { isInteger: true } } } },
+            });
+            const registry  = new SchemaRegistry();
+            const generator = new ApiDocGenerator(action, ControllerClass, registry);
+
+            expect(generator.queryParams.field.schema).toEqual({
+                type:       'object',
+                properties: { widget: { $ref: '#/components/schemas/Widget' }, count: { type: 'integer' } },
+                required:   ['widget', 'count'],
+            });
+            expect(registry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+    });
+
+
+    describe('#documentation', () => {
+        const documented = (overrides = {}) => {
+            const action = { action: 'postIndex', method: 'POST', path: '/things', ...overrides.action };
+            YamlLoader.loadFile.mockReturnValue({
+                description: 'Creates a thing',
+                summary:     'Create thing',
+                responses:   overrides.responses,
+                ...overrides.details,
+            });
+            ControllerClass.parametersForAction.mockReturnValue(overrides.params || {});
+            ControllerClass._authenticationDocumentation.mockReturnValue(overrides.security);
+            return new ApiDocGenerator(action, ControllerClass);
+        };
+
+        it ('assembles the operation object with summary, description, parameters and default responses', () => {
+            const generator = documented({
+                action: { action: 'getIndex', method: 'GET', path: '/things' },
+                params: { q: { isString: true } },
+            });
+
+            expect(generator.documentation).toEqual({
+                operationId: 'thingsGetIndex',
+                summary:     'Create thing',
+                description: 'Creates a thing',
+                parameters:  [{ name: 'q', in: 'query', required: true, description: '', schema: { type: 'string' } }],
+                responses:   { '200': { description: 'Successful response' } },
+            });
+        });
+
+        it ('defaults responses to a 200 stub when the resolver returns null', () => {
+            const generator = documented({ params: {} });
+
+            expect(generator.documentation.responses).toEqual({ '200': { description: 'Successful response' } });
+        });
+
+        it ('treats a missing documentation file as undocumented', () => {
+            YamlLoader.fileExists.mockReturnValue(false);
+            const action    = { action: 'getIndex', method: 'GET', path: '/things' };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.hasDocumentation).toBe(false);
+            expect(YamlLoader.loadFile).not.toHaveBeenCalled();
+        });
+
+        it ('formats description-only responses without a content block', () => {
+            const generator = documented({
+                params:    {},
+                responses: {
+                    '200': { description: 'Created' },
+                    '400': { description: 'Bad request' },
+                },
+            });
+
+            expect(generator.documentation.responses).toEqual({
+                '200': { description: 'Created' },
+                '400': { description: 'Bad request' },
+            });
+        });
+
+        it ('wraps a raw OpenAPI response body in the standard envelope schema', () => {
+            const generator = documented({
+                params:    {},
+                responses: {
+                    '200': {
+                        description: 'A thing',
+                        body:        { type: 'object', properties: { id: { type: 'integer' } }, required: ['id'] },
+                    },
+                },
+            });
+
+            expect(generator.documentation.responses).toEqual({
+                '200': {
+                    description: 'A thing',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type:       'object',
+                                properties: {
+                                    data: {
+                                        type:       'object',
+                                        properties: { id: { type: 'integer' } },
+                                        required:   ['id'],
+                                    },
+                                    status: { type: 'string', example: 'ok' },
+                                },
+                            },
+                        },
+                    },
+                },
+            });
+        });
+
+        it ('places the documented body under the envelope data key', () => {
+            const body = {
+                type:       'object',
+                properties: { id: { type: 'integer', example: 5 }, tags: { type: 'array', items: { type: 'string' } } },
+                required:   ['id'],
+            };
+            const generator = documented({ params: {}, responses: { '200': { description: 'Thing', body } } });
+            const schema    = generator.documentation.responses['200'].content['application/json'].schema;
+
+            expect(schema.type).toEqual('object');
+            expect(schema.properties.data).toEqual(body);
+            expect(schema.properties.status).toEqual({ type: 'string', example: 'ok' });
+        });
+
+        it ('resolves a ref in a response body to a $ref under data and registers the component', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            const generator = documented({
+                params:    {},
+                responses: { '200': { description: 'A widget', body: { ref: Widget } } },
+            });
+
+            expect(generator.documentation.responses['200'].content['application/json'].schema.properties.data)
+                .toEqual({ $ref: '#/components/schemas/Widget' });
+            expect(generator.schemaRegistry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('resolves a ref nested inside a response body schema', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            const generator = documented({
+                params:    {},
+                responses: {
+                    '200': {
+                        description: 'Widgets',
+                        body:        { type: 'object', properties: { items: { type: 'array', items: { ref: Widget } } } },
+                    },
+                },
+            });
+
+            expect(generator.documentation.responses['200'].content['application/json'].schema.properties.data).toEqual({
+                type:       'object',
+                properties: { items: { type: 'array', items: { $ref: '#/components/schemas/Widget' } } },
+            });
+            expect(generator.schemaRegistry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('adds an errors object to the envelope for responses >= 400', () => {
+            const generator = documented({
+                params:    {},
+                responses: {
+                    '400': {
+                        description: 'Bad request',
+                        body:        { type: 'object', properties: { id: { type: 'integer' } } },
+                    },
+                },
+            });
+
+            expect(generator.documentation.responses['400'].content['application/json'].schema).toEqual({
+                type:       'object',
+                properties: {
+                    data:   { type: 'object', properties: { id: { type: 'integer' } } },
+                    status: { type: 'string', example: 'bad request' },
+                    errors: {
+                        type:       'object',
+                        properties: {
+                            message: { type: 'string', nullable: true },
+                            fields:  { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
+                        },
+                    },
+                },
+            });
+        });
+
+        it ('flattens the body into the envelope for a spread (V2) formatResponseBody', () => {
+            YamlLoader.loadFile.mockReturnValue({
+                description: 'Creates a thing',
+                responses:   {
+                    '200': {
+                        description: 'A thing',
+                        body:        { type: 'object', properties: { id: { type: 'integer' } }, required: ['id'] },
+                    },
+                },
+            });
+            V2ControllerClass.parametersForAction.mockReturnValue({});
+            const action    = { action: 'postIndex', method: 'POST', path: '/things' };
+            const generator = new ApiDocGenerator(action, V2ControllerClass);
+
+            expect(generator.documentation.responses['200'].content['application/json'].schema).toEqual({
+                type:       'object',
+                properties: {
+                    success: { type: 'boolean', example: true },
+                    id:      { type: 'integer' },
+                },
+                required: ['id'],
+            });
+        });
+
+        it ('wraps a $ref body in allOf for a spread (V2) formatResponseBody', () => {
+            class Widget { static documentationSchema() { return { name: { type: 'string' } }; } }
+            YamlLoader.loadFile.mockReturnValue({
+                description: 'Creates a widget',
+                responses:   { '201': { description: 'Created', body: { ref: Widget } } },
+            });
+            V2ControllerClass.parametersForAction.mockReturnValue({});
+            const action    = { action: 'postIndex', method: 'POST', path: '/things' };
+            const generator = new ApiDocGenerator(action, V2ControllerClass);
+
+            expect(generator.documentation.responses['201'].content['application/json'].schema).toEqual({
+                type:       'object',
+                properties: { success: { type: 'boolean', example: true } },
+                allOf:      [{ $ref: '#/components/schemas/Widget' }],
+            });
+            expect(generator.schemaRegistry.schemas.Widget).toEqual({ type: 'object', properties: { name: { type: 'string' } } });
+        });
+
+        it ('adds a requestBody with a required list for POST body params', () => {
+            const generator = documented({
+                params: {
+                    foo: { isString: true },
+                    opt: { isInteger: { gte: 0 }, optional: true },
+                },
+            });
+
+            expect(generator.documentation.requestBody).toEqual({
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                foo: { type: 'string', description: '' },
+                                opt: { type: 'integer', minimum: 0, description: '' },
+                            },
+                            required: ['foo'],
+                        },
+                    },
+                },
+            });
+        });
+
+        it ('omits requestBody when there are no body params', () => {
+            const generator = documented({
+                action: { action: 'getIndex', method: 'GET', path: '/things' },
+                params: {},
+            });
+
+            expect(generator.documentation).not.toHaveProperty('requestBody');
+        });
+
+        it ('infers a multipart/form-data body when a body param is a binary file', () => {
+            const generator = documented({
+                params: { file: { isString: true, format: 'binary' } },
+            });
+
+            expect(generator.documentation.requestBody.content).toEqual({
+                'multipart/form-data': {
+                    schema: {
+                        type:       'object',
+                        properties: { file: { type: 'string', format: 'binary', description: '' } },
+                        required:   ['file'],
+                    },
+                },
+            });
+        });
+
+        it ('includes security when the action is authenticated', () => {
+            const generator = documented({ params: {}, security: [{ apiKeyAuth: [] }] });
+
+            expect(generator.documentation.security).toEqual([{ apiKeyAuth: [] }]);
+        });
+
+        it ('omits security when the action is not authenticated', () => {
+            const generator = documented({ params: {}, security: undefined });
+
+            expect(generator.documentation).not.toHaveProperty('security');
+        });
+    });
+
+
+    describe('description / default / format pass-through', () => {
+        it ('puts description on the parameter object and default in its schema', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                q: { isString: true, description: 'Search term', default: 'all' },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams.q).toEqual({
+                name: 'q', in: 'query', required: true, description: 'Search term',
+                schema: { type: 'string', default: 'all' },
+            });
+        });
+
+        it ('puts description and default on a body property schema', () => {
+            const action = { action: 'postIndex', method: 'POST', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                foo: { isString: true, description: 'A thing', default: 'x' },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.bodyProperties.foo).toEqual({ type: 'string', default: 'x', description: 'A thing' });
+        });
+
+        it ('passes a format hint through to the schema', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ email: { isString: true, format: 'email' } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams.email.schema).toEqual({ type: 'string', format: 'email' });
+        });
+
+        it ('passes nullable through to the schema', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ q: { isString: true, nullable: true } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams.q.schema).toEqual({ type: 'string', nullable: true });
+        });
+
+        it ('places a parameter example at the parameter level, not inside the schema', () => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            ControllerClass.parametersForAction.mockReturnValue({ q: { isString: true, example: 'blue widgets' } });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams.q).toEqual({
+                name: 'q', in: 'query', required: true, description: '',
+                schema:  { type: 'string' },
+                example: 'blue widgets',
+            });
+        });
+    });
+
+
+    describe('#operationId', () => {
+        it ('combines the controller name and action', () => {
+            const action    = { action: 'getIndex', method: 'GET', path: '/things' };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.operationId).toEqual('thingsGetIndex');
+        });
+
+        it ('falls back to the action alone when the controller has no name', () => {
+            const action          = { action: 'getIndex', method: 'GET', path: '/things' };
+            const namelessClass   = { parametersForAction: jest.fn() };
+            const generator       = new ApiDocGenerator(action, namelessClass);
+
+            expect(generator.operationId).toEqual('getIndex');
+        });
+    });
+
+
+    describe('#tags', () => {
+        const tagged = (tagsReturn) => {
+            const action = { action: 'getIndex', method: 'GET', path: '/things' };
+            YamlLoader.loadFile.mockReturnValue({ description: 'Lists things' });
+            ControllerClass.parametersForAction.mockReturnValue({});
+            ControllerClass._tagsDocumentation.mockReturnValue(tagsReturn);
+            return new ApiDocGenerator(action, ControllerClass);
+        };
+
+        it ('delegates to the controller _tagsDocumentation with the action name', () => {
+            const generator = tagged(['Things']);
+
+            expect(generator.tags).toEqual(['Things']);
+            expect(ControllerClass._tagsDocumentation).toHaveBeenCalledWith('getIndex');
+        });
+
+        it ('emits documentation.tags when the controller returns a non-empty list', () => {
+            const generator = tagged(['Things', 'Admin']);
+
+            expect(generator.documentation.tags).toEqual(['Things', 'Admin']);
+        });
+
+        it ('omits tags when the controller returns an empty list', () => {
+            const generator = tagged([]);
+
+            expect(generator.documentation).not.toHaveProperty('tags');
+        });
+
+        it ('omits tags when the controller returns undefined', () => {
+            const generator = tagged(undefined);
+
+            expect(generator.documentation).not.toHaveProperty('tags');
+        });
+    });
+});