swagger-mock-api

#mock-api

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.

• mock-api
  • installation
  • Using the middleware
    • Ignoring specific paths
  • Specifying custom Chance options
  • A note on types:
    • Returning Fixed values

installation

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:

grunt.loadNpmTasks('grunt-contrib-connect');

Then, configure a task like so:

'use strict';

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

module.exports = function(grunt) {

  grunt.initConfig({
    connect: {
      server: {
        options: {
          keepalive: true,
          middleware: [
            mockApi({
                  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.loadNpmTasks('grunt-contrib-connect');

  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.

  // ....
  mockApi({
    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.

...
definitions:
  NewPet:
    properties:
      name:
        type: string
        x-chance-type: name
      tag:
        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:

...
definitions:
  Pet:
    allOf:
      - $ref: '#/definitions/NewPet'
      - required:
        - id
        properties:
          id:
            type: integer
            format: int64
            x-type-options:
              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:

    status:
      type: object
      x-chance-type: fixed
      x-type-value:
        type: 'adopted'