x-mock/README.md

Mock response generator for OAS.

# x-mock
Mock response generator for OAS based on extending the response mocking subset of the [Swagmock](https://github.com/subeeshcbabu/swagmock) project. The goal is to create a complete Swagger based response mocking solution that supports customization via an x-mock schema extension. Please see the [Drunken Master](https://github.com/buchenberg/drunken-master) project for a working example of how it is being used.

## Install

```
npm install x-mock
```

## Usage

```javascript
    const Xmock = require('x-mock');
    const Mockgen = Xmock(api, options);
```

Promise response:

```javascript
    let responseMock = Mockgen.response({
        path: '/pet/findByStatus',
        operation: 'get',
        response: 200
    }); 
    //returns a promise that resolves to response mock
    responseMock.then(mock => {
        // use mock
    }).catch(error => {
        // deal with error
    });
```

Callback style:

```javascript

    Mockgen.response({
        path: '/pet/findByStatus',
        operation: 'get',
        response: 200
    }, (error, mock) => {
        // deal with error or use mock here
    });
```

Check the [API](README.md#api) for more details.

## Example

Initialize the mock generator

```javascript
    const apiPath = 'http://petstore.swagger.io/v2/swagger.json';
    const Xmock = require('x-mock');

    const Mixins = [
        {
            'dogname': function () {
                return 'Fido'
            }
        }
    ]
    const Mockgen = Xmock(apiPath, { 
        'validated': true, 
        'mixins': Mixins
        });
```

Response mock generation:

```javascript
    Mockgen.response({
        path: '/pet/findByStatus',
        operation: 'get',
        response: 200
    }).then(mock => {
        console.log(mock); // This would print:
        // {
        //     "id": 2530624032210944,
        //     "category": {
        //         "id": 8200505595527168,
        //         "name": "r($vA&"
        //     },
        //     "name": "doggie",
        //     "photoUrls": ["p0x1", "6O)3*kO"],
        //     "tags": [{
        //         "id": 4590764340281344,
        //         "name": "WCTA6f!"
        //     }, {
        //         "id": -4614156653166592,
        //         "name": "e"
        //     }],
        //     "status": "pending"
        // }
    }).catch(error => {
        console.log(error);
    });
```

Check [Examples](docs/EXAMPLES.md) for more details on mock generators.

## API

`Xmock(api, [options])`

* `api` - (*Object*) or (*String*) or (*Promise*) - (required) - api can be one of the following.
    - A relative or absolute path to the Swagger api document.
    - A URL of the Swagger api document.
    - The swagger api Object
    - A promise (or a `thenable`) that resolves to the swagger api Object

* `options` - (*Object*) - (optional) - Additional options to create the mock generator.
    - `validated` -  (*Boolean*) - Set this property to `true` if the api is already validated against swagger schema and already dereferenced all the `$ref`. This is really useful to generate mocks for parsed api specs. Default value for this is `false` and the api will be validated using [swagger-parser validate](https://github.com/BigstickCarpet/swagger-parser/blob/master/docs/swagger-parser.md#validateapi-options-callback).
        ```javascript
        'validated': true
        ```
    - `mixins` - (*Array*)  - This an array of [Chance mixins](http://chancejs.com/#mixin) that may be called in x-mock functions (see [Examples](docs/EXAMPLES.md)). Although you may return any string, number, or object, it is strongly suggested that you return a value of the type that you are mocking for. This will be enforced in a further release.
        ```javascript
        [
            {
                'dogname': function () {
                    return 'Fido'
                }
            },
            {
                'foobar': function () {
                    return 'Foo' + 'Bar'
                }
            },
            {
                'fooBarObj': function () {
                    return { 'foo': 'bar' }
            }
        ]
        ```

## response

`mockgen.response(options, [callback])`

This generates the mock response object based on the `options`

* `options` - (*Object*) - (required) - Options to control the mock generation.

* `callback` -  (*Function*) - (optional) - `function (error, mock)`. If a callback is not provided a `Promise` will be returned.

### options

* `path` - (*String*) - (required) - The path for which the response mock need to be generated. For example `/pet/findByStatus`, `/pet` etc.

* `operation` - (*String*) - (required) - The operation for which the response mock need to be generated. For example `get`, `post` etc. 

* `response` - (*String*) - (required) - The response for which the response mock need to be generated. For example `200`, `400`, `default` etc.

## Examples

### API
[Usage](docs/EXAMPLES.md)