Skip to content
A connect-compatible middleware for mocking a Swagger spec API
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo Support for pattern May 28, 2016
LICENSE Enabled reloading when swagger file changes Aug 3, 2015


This module is a connect-compatible middleware generating function that generates an API based on a Swagger 2.0 compatible YAML or JSON file. All data returned is generated by chance.


The primary use case is to be run as a middleware for grunt-contrib-connect. Run the following command:

npm install swagger-mock-api

Using the middleware

Assuming the API is to be run from a grunt task, ensure the following module has also been installed via npm:

  • grunt-contrib-connect

If you're not auto-loading grunt tasks, find in your Gruntfile where the tasks are being loaded and add the line:


Then, configure a task like so:

'use strict';

var path = require('path');
var mockApi = require('swagger-mock-api');

module.exports = function(grunt) {

    connect: {
      server: {
        options: {
          keepalive: true,
          middleware: [
                  swaggerFile: path.join(__dirname, 'path to swagger YAML or JSON file'),
                  watch: true // enable reloading the routes and schemas when the swagger file changes


  grunt.registerTask('default', ['connect']);

Ignoring specific paths

There are two mutually exlusive options: ignorePaths and mockPaths; the former specifies which paths to ignore, while the latter specifies the only paths that should be mocked. Depending on what state of completion the backend API is in, you may want to start with ignorePaths (adding as the API improves) and eventually switch over to mockPaths and remove until the API is complete.

  // ....
    swaggerFiles: 'path-to-file',

    ignorePaths: [
      'PUT DELETE /pets/{id}', // you can ignore specific methods of a path
      '/pets/{id}'             // or ignore EVERY method for a path

Specifying custom Chance options

Swagger specifies only a few primitive types; for scenarios where specific chance methods are needed, use the x-chance-type field.

        type: string
        x-chance-type: name
        type: string
        x-chance-type: guid

Most of the chance methods allow some fine-tuning of the returned data. For example, the integer method allows specification of minimum and maximum output values. These options can be configured in the Swagger YAML file with the x-chance-options block:

      - $ref: '#/definitions/NewPet'
      - required:
        - id
            type: integer
            format: int64
              min: 1
              max: 1000

A note on types:

All of the primitive types defined in the Swagger specification are supported except for file and password. Currently, the format property is ignored; use x-chance-type instead. The server will error on any request with a type other than one of the primitive types if there is no valid x-chance-type also defined.

Returning Fixed Values

Although not a chance method, support has been added for returning fixed values using x-chance-type: fixed. Any value given for the custom tag x-type-value will be returned; below is an example where an object is returned:

      type: object
      x-chance-type: fixed
        type: 'adopted'
You can’t perform that action at this time.