swagger-enforcer

Contents

• Examples
• API
• Enforcement Options

Examples

Example 1

const Enforcer = require('swagger-enforcer');

// a schema to enforce
const schema = {
    type: 'object',
    properties: {
        num: {
            type: 'number',
            minimum: 0
        },
        str: {
            type: 'string',
            enum: ['foo', 'bar', 'baz'],
            default: 'foo'
        }
    }
};

// define swagger schema definitions
const definitions = {};

// define enforcer options
const options = { useDefaults: true };

// create enforcer instance that defines which rules to enforce
const enforcer = Enforcer(schema, definitions, options);

// build an object that enforces the schema
const obj = enforcer.enforce();

console.log(obj);       // { str: 'foo' } - this is because 'str' had a default value: 
obj.num = 5;            // validates successfully and value is set
obj.str = 'abc';        // throws an error because 'abc' is not in enum

const Enforcer = require('swagger-enforcer');

// a schema to enforce
const schema = {
    type: 'object',
    properties: {
        num: {
            type: 'number',
            minimum: 0
        },
        str: {
            type: 'string',
            enum: ['foo', 'bar', 'baz'],
            default: 'foo'
        }
    }
};

// create enforcer instance that defines which rules to enforce
const enforcer = Enforcer(schema, {}, { useDefaults: true });

// build the object
const obj = {
    num: 5,
    str: 'abc'
};

// validate the object
enforcer.validate(schema, obj);  // throws an error because 'abc' is not in enum

- [Enforcer.prototype.enforce](#enforcerprototypeenforce) - Create an object with enforcement.
- [Enforcer.prototype.errors](#enforcerprototypeerrors) - Run a full validation of an value and get back an array of Error objects.
- [Enforcer.prototype.validate](#enforcerprototypevalidate) - Run a full validation of an value.

- [defaults](#enforcerapplytemplatedefaults)

- [defaults](#enforcerinjectparametersdefaults) - Set injectParameter defaults

- [binary](#enforceris)
- [boolean](#enforcerisboolean)
- [byte](#enforcerisbyte)
- [date](#enforcerisdate)
- [dateTime](#enforcerisdatetime)
- [integer](#enforcerisinteger)
- [number](#enforcerisnumber)

- [binary](#enforcertobinary)
- [boolean](#enforcertoboolean)
- [byte](#enforcertobyte)
- [date](#enforcertodate)
- [dateTime](#enforcertodatetime)
- [integer](#enforcertointeger)
- [number](#enforcertonumber)

```
{
    Pet: {
        type: 'object',
        discriminator: 'petType',
        properties: {
            name: {
                type: 'string'
            },
            petType: {
                type: 'string'
            }
        },
        required: ['name', 'petType']
    },
    Cat: {
        type: 'object',
        allOf: [
            {
                $ref: '#/definitions/Pet'
            },
            {
                type: 'object',
                properties: {
                    name: {
                        type: 'string'
                    },
                    petType: {
                        type: 'string'
                    },
                    huntingSkill: {
                        type: string
                    }
                }                
            }
        ]
    }
}
```

```
{
    autoFormat: false,
    enforce: {
        enum: true,
        maxItems: true,
        minItems: false,
        uniqueItems: true,
        multipleOf: true,
        maximum: true,
        minimum: true,
        maxLength: true,
        minLength: true,
        pattern: true,
        additionalProperties: true,
        maxProperties: true,
        minProperties: false,
        required: false
    },
    useDefaults: false
}
```

Enforcer.prototype.enforce

• initial - An optional value to initialize the enforcement with.

Enforcer.prototype.errors

• value - An value to validate.

Enforcer.prototype.validate

• value - An value to validate.

Enforcer.applyTemplate

• schema - The schema to build objects from.

• definitions - The swagger definitions object. This is necessary if using discriminators, otherwise it can safely be set to an empty object {} or null.

• params - An object defining key value pairs for parameter enforcement.

• options - The options to use while building the object:

- *autoFormat* - Any value set using `x-variable` will will automatically by type cast and formatted when possible to match the schema. Defaults to `true`.

- *defaultsUseParams* - If applying `useDefaults` is set to true and this property is set to true then parameter replacement will also be set for defaults. Defaults to `true`.

- *ignoreMissingRequired* - If set to `false` and any requires are missing in the schema then that part of the template will not be stampped. Defaults to `true`

- *replacement* - Set the parameter replacement style to one of `colon`, `doubleHandlebar`, `handlebar`, or a custom `Function`. Defaults to `handlebar`.

- *useDefaults* - Set to true to use `default` property in addition to `x-template` property to generate templates. Defaults to `true`.

- *useTemplates* - Set to `true` to use the `x-template` property to produce string replacements. Defaults to `true`.

- *useVariables* - Set to `true` to use the `x-variable` property to place values. Defaults to `true`.

• initialValue - An optional value to start building the object from. If provided it must match the schema's type.

const schema = {
    type: 'object',
    properties: {
        firstName: {
            type: 'string',
            'x-template': '{firstName}'
        },
        fullName: {
            type: 'string',
            'x-template': '{firstName} {lastName}'
        },
        lastName: {
            type: 'string',
            'x-template': '{lastName}'
        },
        birthday: {
            type: 'string',
            format: 'date',
            'x-variable': 'birthday'
        },
        roles: {
            type: 'array',
            items: {
                type: 'string'
            },
            default: []
        }
    }
};

const params = {
    birthday: new Date(),
    firstName: 'Bob',
    lastName: 'Smith'
};

const x = Enforcer.applyTemplate(schema, null, params);

console.log(x);         //  {
                        //      firstName: 'Bob',
                        //      fullName: 'Bob Smith',
                        //      lastName: 'Smith',
                        //      birthday: '2000-01-01'
                        //      roles: []
                        //  }

Enforcer.applyTemplate.defaults

Enforcer.applyTemplate.defaults = {
    autoFormat: true,
    defaultsUseParams: true,
    useDefaults: true,
    useTemplates: true,
    useVariables: true,
    replacement: 'handlebar'
};

Enforcer.injectParameters

• value - The value to begin traversing and looking for strings to replace.

• parameters - An object with keys and values that represent what to replace in each string.

• options - Configuration options:

* *mutate* - Set to `true` to mutate the passed in object, otherwise generate a copy. Defaults to `false`.

* *replacement* - The replacement method to use. This can be one of `colon`, `doubleHandlebar`, `handlebar`, or a custom `Function`. Defaults to `handlebar`.

const o = {
    foo: '{name} is {age} years old {when}'
};

const params = {
    name: 'Bob',
    age: 25,
    when: 'today'
};

const x = Enforcer.injectParameters(o, params);

console.log(x.foo);         // 'Bob is 25 years old today'

Enforcer.injectParameters.defaults

Enforcer.injectParameters.defaults = {
    mutate: false,
    replacement: 'handlebar'
};

Enforcer.is

• binary
• boolean
• byte
• date
• dateTime
• integer
• number

Enforcer.is.binary

• value - The value to test.

Enforcer.is.binary('00101000');    // true

Enforcer.is.boolean

• value - The value to test.

Enforcer.is.boolean('true');    // true

Enforcer.is.byte

• value - The value to test.

Enforcer.is.byte('aGVsbG8=');    // true

Enforcer.is.date

• value - The value to test.

Enforcer.is.date('2000-01-01');    // true

Enforcer.is.dateTime

• value - The value to test.

Enforcer.is.dateTime('2000-01-01T00:00:00.000Z');    // true

Enforcer.is.integer

• value - The value to test.

Enforcer.is.integer('15');    // true

Enforcer.is.number

• value - The value to test.

Enforcer.is.number('15.27');    // true

Enforcer.release

• value - The value to release from enforcement.

const Enforcer = require('swagger-enforcer');

const enforcer = Enforcer();

const schema = {
    type: 'array',
    items: {
        type: 'number'
    }
};

const array = enforcer.enforce(schema, []);

try {
    // throws an error because the item is not a string
    array.push('a');   
} catch (e) {
    console.error(e.stack);
}

// release the enforcement
const released = Enforcer.release(array);

// no error thrown
released.push('a');

Enforcer.same

• value1 - The first value to compare.

• value2 - The second value to compare.

Enforcer.same({ a: 1, b: 2 }, { b: 2, a: 1 });    // true

Enforcer.to

• binary
• boolean
• byte
• date
• dateTime
• integer
• number

Enforcer.to.binary

• value - The value to convert. The value can be a boolean, number, string, or buffer.

Enforcer.to.binary(1);    // '00000001'

Enforcer.to.boolean

• value - The value to convert. The value can be of any type.

Enforcer.to.boolean('hello');    // true

Enforcer.to.byte

• value - The value to convert. The value can be a boolean, number, string, or buffer.

Enforcer.to.byte('hello');    // 'aGVsbG8='

Enforcer.to.date

• value - The value to convert. The value can be a Date, number, or string.

Enforcer.to.date(new Date(2000, 0, 1, 0, 0, 0, 0));    // '2000-01-01'

Enforcer.to.dateTime

• value - The value to convert. The value can be a Date, number, or string.

Enforcer.to.dateTime(new Date(2000, 0, 1, 0, 0, 0, 0));    // '2000-01-01T00:00:00.000Z'

Enforcer.to.integer

• value - The value to convert. The value can be a boolean, number, or numeric string.

Enforcer.to.integer('15');    // 15

Enforcer.to.number

• value - The value to convert. The value can be a boolean, number, or numeric string.

Enforcer.to.number('1.23');    // 1.23

Enforcement Options

{
    autoFormat: false,
    enforce: {
        enum: true,
        maxItems: true,
        minItems: false,
        uniqueItems: true,
        multipleOf: true,
        maximum: true,
        minimum: true,
        maxLength: true,
        minLength: true,
        pattern: true,
        additionalProperties: true,
        maxProperties: true,
        minProperties: false,
        required: false
    },
    useDefaults: false
}

• autoFormat - Whether to attempt to convert any values being set to their appropriate types. For example, if a schema expects a string of format date-time and this option is set to true then you can set the schema using a Date object and that object will automatically be converted to a string in date-time format. The advantage of using this is that it means you can skip to explicit use of the conversion to api but the disadvantage is that it may obscure some errors if the conversion shouldn't have happened. Defaults to false.

• enforce - An object specifying the validation rules to enforce while building or validating a schema. If this value is set to true then all enforcement properties will be set to true. Conversely, if this value is set to false then all enforcement properties will be set to false. Some properties default to being disabled (false) because they would make it hard to build an object that is under active enforcement.

**General Enforcement**

* *enum* - Enforce that any values added match an item in the enum. Defaults to `true`.

**Array Enforcement**

* *maxItems* - Enforce that the array is not populated above its maxItems threshold. Defaults to `true`.

* *minItems* - Enforce that the array is never smaller than its minItems threshold. Defaults to `false`.

* *uniqueItems* - Enforce that each item in the array is always unique. Enabling this option may significantly increase processing time (more so for nested objects and arrays). Defaults to `true`.

**Number and Integer Enforcement** 

* *multipleOf* - Enforce multipleOf validation for numbers and integers. Defaults to `true`.

* *maximum* - Enforce maximum validation for numbers and integers. Defaults to `true`.

* *minimum* - Enforce minimum validation for numbers and integers. Defaults to `true`.

**String Enforcement** 

* *maxLength* - Enforce maxLength validation. Defaults to `true`.

* *minLength* - Enforce minLength validation for numbers and integers. Defaults to `true`.

* *pattern* - Enforce pattern matching. Defaults to `true`.

**Object Enforcement** 

* *additionalProperties* - Enforce additional property validation. Defaults to `true`.

* *maxProperties* - Enforce maxProperties validation. Defaults to `true`.

* *minProperties* - Enforce minProperties validation for numbers and integers. Defaults to `false`.

* *required* - Enforce that required properties are set. Defaults to `false`.

• useDefaults - Whether to use default values to build out the swagger response object automatically, as much as possible. Defaults to false.