0.3.14 • Public • Published


    Sans-Server middleware that uses swagger documents to define routes, validate requests, validate responses, and to produce mocks.

    Table of Contents


    The following example will produce mock responses using response examples for any incoming requests. You can add actual implementations through controllers.

    A complete example can be found in the example directory.

    const Server = require('sans-server');
    const Swagger = require('sans-server-swagger');
    const Router = require('sans-server-router');
    // define the server
    const server = Server();
    // define the swagger middleware with a router
    const swaggerMiddleware = Swagger({
        controllers: './controllers',
        development: true,
        exception: function(res, state) {
                status: state.statusCode,
                message: state.body
        swagger: './swagger.json'
    // use the swagger middleware
    // make a request against the server
    server.request({ method: 'GET', path: '/v1/path/to/call' })
        .then(function(res) {


    The swagger middleware is generated using a configuration with the following properties:

    • controllers - [REQUIRED] The directory path to JavaScript files that contain the methods to execute to fulfill web service requests.

    • development - [OPTIONAL] If true then mocks will automatically be produced from examples when a controller does not exist. Additionally not all controllers must exist. If set to false then all controller implementations must exist. Defaults to false.

    • exception - [OPTIONAL] A function that will get called if the middleware is unable to provide an expected response. This function will receive two parameters: 1) res - the response object, and 2) state - the current response state data. Use the response object to make any modifications to the response before it is returned.

      This function will be called when 1) the response does not meet the response schema defined by swagger, 2) the response uses a status code that is not defined by swagger, 3) the request has invalid input, and 4) when a response is not implemented.

    • ignoreBasePath - [OPTIONAL] If true then the swagger base path will not be used in the routes. Defaults to false.

    • mockQueryParameter - [OPTIONAL] The query parameter to look for when a response should be manually mocked. Defaults to mock.

    • swagger - [REQUIRED] The swagger file that defines the services. This can be either a json or a yaml file.

    Helper Methods


    Convert an 8-bit binary string, made of 0s and 1s, into a Buffer object.

    Signature: req.deserialize.binary ( value: String ) : Buffer


    • value - An 8-bit binary string made of 0s and 1s.

    Returns a Buffer.

    const buffer = req.deserialize.binary('00000010');


    Convert a base64 encoded string into a Buffer object.

    Signature: req.deserialize.byte ( value: String ) : Buffer


    • value - A base64 encoded string.

    Returns a Buffer.

    const buffer = req.deserialize.binary('aGVsbG8=');

    Convert a date string (formatted as YYYY-MM-DD) into a Date object.

    Signature: ( value: String ) : Date


    • value - A date string, formatted as YYYY-MM-DD.

    Returns a Date.

    const date ='2000-01-01');


    Convert an ISO date string into a Date object.

    Signature: req.deserialize.dateTime ( value: String ) : Date


    • value - An ISO date string.

    Returns a Date.

    const date = req.deserialize.dateTime('2000-01-01T00:00:00.000Z');


    Get an object that represents the swagger schema for the current request path and method.

    const swagger = req.swagger.rel;


    Get an object that represents the swagger document from its root.

    const swagger = req.swagger.root;



    See res.swagger.enforce


    A shortcut method to get a response example.

    Signature: res.swagger.example ( [ code: String | Number [, type: String ] ] ) : *


    • code - An optional parameter for the response code. If omitted then the first response code will be used.

    • type - An optional parameter specifying the content-type to use for the example. If omitted then the value will be derived from the request's Accept header.

    Returns a value derived from the example.

    const result = res.swagger.example(200);


    Begin building an object with line by line enforcement. As you mutate the object each change will be validated against the expected swagger response. Also implements defaults automatically as possible. If the response is not an object then continual enforcement will not be in effect, although it will validate the initial value.

    Read more about enforcement

    Signature: res.swagger.enforce ( code: String | Number [, initialValue: * ] ) : *


    • code - The response code the enforce the response for.

    • initialValue - An optional value to initialize with.

    Returns the data type that is being enforced.

    const result = res.swagger.enforce(200);


    Out of the box and using the example above this middleware will produce mock responses. To write implementations for your swagger endpoints you needs to set up controllers.

    You can look at the example directory contained within this project for details.

    In summary:

    1. You need a directory where you will place all of your controller files. This directory is specified by the controller option when creating the middleware.

      const swaggerMiddleware = Swagger({
          controllers: './controllers',
    2. Each path's controller implementation is defined by it's x-controller and operationId.

      • x-controller is the name of the file within the controllers directory that implements the function defined by the operationId. The x-controller can be defined for the entire swagger document, for a specific path, or for a specific method within a path by defining this property at those different levels within your swagger document. An x-controller defined at one level can be overwritten by another x-controller at a more specific level.

      • operationId is the name of the property within your controller that has the function to execute. This function will receive as parameters the sans-server request and response objects.

      For example purposes only, in the following example the x-controller is defined at the document level, the path level, and the method level. In actuality, the x-controller only needs to be defined at each appropriate level once. If defined at the document level then all paths and methods will use that controller unless a specific path or method has an x-controller specified as something else.

      x-controller: pets              # All methods for all paths will use pets.js controller unless overwritten 
          x-controller: pets          # This path will use the pets.js controller for all methods within this path unless overwritten 
            x-controller: pets        # This method within this path will use the pets.js controller 
            summary: List all pets
            operationId: listPets     # Implementation looked for in exports.listPets in pets.js file 



    Mocked responses will be validated against the swagger response definition.

    Mock Sources

    In order for mocks to work there must be a source. Mocks can be produced from two sources:

    1. From examples within the swagger document:

            summary: List all pets
            operationId: listPets
                description: An paged array of pets
                  application/json:     # Mocks will be produced from examples 
                  id: 123
                    name: Sparky
                    tag: Dog
                  id: 456
                    name: Ghost
                    tag: Cat
                  id: 789
                    name: Goldy
                    tag: Fish
                  "$ref": "#/definitions/Pets"
    2. From an implemented mock in a controller:

      // until this implementation is complete we can have it call the custom mock
      exports.listPets = function(req, res) {
          exports.listPets.mock(req, res);     // call the mock
      // a custom mock for this implementation
      exports.listPets.mock = function(req, res) {
                  id: 123,
                  name: "Sparky",
                  tag: "Dog"
                  id: 456,
                  name: "Ghost",
                  tag: "Cat"
                  id: 789,
                  name: "Goldy",
                  tag: "Fish"

    Automatic vs Manual Mocking

    Automatic Mocking

    Automatic mocking only works if these conditions are met:

    1. The configuration must have the development option set to true.

    2. There must be no implementation for the endpoint being hit.

    3. There must be a mock source.

    For mocks that are sourced from the swagger document examples the swagger response that is defined first will be used to determine the mock being sent back. Additionally the request's Accept header will be used to determine which example to send back. If the request's Accept header is not set then the first example's content type will be used.

    Manual Mocking

    Mocks can be used manually even when an implementation exists or when not in development mode.

    Manual mocking only works if these conditions are met:

    1. The swagger definition for the path being mocked must specify the mocked query parameter as a swagger query parameter.

    2. The incoming request has a query parameter that matches the mocked query parameter.

    3. There must be a mock source.

    For mocks that are sourced from the swagger document examples the mocked query parameter value is used in conjunction with the request's Accept header to determine which response example to send back. If the request's Accept header is not set then the first example's content type will be used.

    Testing Response Examples

    There is no need to write test cases for all of your swagger response examples. A tool has been provided that will do this for you.

    Validate Response Examples using Terminal/Command Line

    For this to work you'll need to install the sans-server-swagger module globally npm install -g sans-server-swagger. Then run the following command with the parameter being the path to your swagger file:

    sans-server-swagger ./swagger.yaml

    Validate With Mocha

    const expect = require('chai').expect;
    const Swagger = require('sans-server-swagger');
    describe('my tests', () => {
        it('examples are valid', () => {
            return Swagger.testSwaggerResponseExamples('./swagger.yaml')
                .then(results => expect(results.percentage).to.equal(1));

    Validate With Tape

    const Swagger = require('sans-server-swagger');
    const test = require('tape');
    test('my tests', t => {
            .then(results => t.equal(results.percentage, 1));

    Swagger Enforcer

    This package uses the swagger-enforcer package to perform validation. The swagger-enforcer has been exposed through this package. This is especially useful for its type conversion and parameter injection tools.

    const Swagger = require('sans-server-swagger');
    const Enforcer = Swagger.Enforcer;
    const date = Date());
    console.log(date);      // a string of "2000-01-01" (or whatever the date actually is)

    Response Enforcement

    You can enforce a response while it is being built by using the swagger-enforcer. As of now the enforced rules are the defaults.

    To enforce a response while building you only need to specify which response you'll be building. Below you can see an implemented controller method that uses the building enforcement: = function(req, res) {
        const result = res.enforce(200);    // 200 - the response code to enforce
        result.firstName = 'Bob';           // an error will be thrown here if this is an invalid mutation of the result
        result.lastName = 'Smith';          // an error will be thrown here if this is an invalid mutation of the result

    Additionally you can optionally set the initial value: = function(req, res) {
        const result = res.enforce(200, { firstName: 'Bob' });  // will throw an error here if initial value is invalid
        result.lastName = 'Smith';          // an error will be thrown here if this is an invalid mutation of the result


    npm i sans-server-swagger

    DownloadsWeekly Downloads






    Unpacked Size

    168 kB

    Total Files


    Last publish


    • gi60s