x-mock/docs/EXAMPLES.md

Mock response generator for OAS.

# Xmock examples

Swagger api : http://petstore.swagger.io/v2/swagger.json

Mock examples are based on extending the above swagger api.

## Default Response

The following code generates a response mock for the path `/pet/findByStatus`, operation `get` and response `200`. In this case, no OAS response schema extensions are being used - just the plain old specification.

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

    Mockgen.response({
        path: '/pet/findByStatus',
        operation: 'get',
        response: 200
    }, function (error, mock) {
        console.log(mock);    
    });
```
##### Mock sample

```json
    {
        "response": {
            "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"
        }
    }
```
The above mock was based on the Pet schema found in the swagger at http://petstore.swagger.io/v2/swagger.json.

```json
"Pet": {
    "type": "object",
    "required": [
    "name",
    "photoUrls"
    ],
    "properties": {
    "id": {
        "type": "integer",
        "format": "int64"
    },
    "category": {
        "$ref": "#/definitions/Category"
    },
    "name": {
        "type": "string",
        "example": "doggie"
    },
    "photoUrls": {
        "type": "array",
        "xml": {
        "name": "photoUrl",
        "wrapped": true
        },
        "items": {
        "type": "string"
        }
    },
    "tags": {
        "type": "array",
        "xml": {
        "name": "tag",
        "wrapped": true
        },
        "items": {
        "$ref": "#/definitions/Tag"
        }
    },
    "status": {
        "type": "string",
        "description": "pet status in the store",
        "enum": [
        "available",
        "pending",
        "sold"
        ]
    }
    },
    "xml": {
    "name": "Pet"
    }
}
```

For each of the above schema properties, x-mock evatuates the following basic conditions going from more specific to more general.

1) Does the property contain an `x-mock` object? If so, base the mock on that.
1) Does the property contain an `x-example`? If so, base the mock on that value.
1) Does the property contain an `example`? If so, base the mock on that value. In the above example, the `name` property has an `example`.
    ```json
    "name": {
        "type": "string",
        "example": "doggie"
    }
    ```
1) Otherwise, use `type` value to produce a reponse value.

In our first example, with the exception of `name`, x-mock uses the schema `type` value to produce random mock values.

## x-mock OAS schema extensions

x-mock uses a meta programming model to define mocks where possible. The following OAS extensions are used to define the required mock responses.

### x-example

This extension is used in the response schema definitions at the property level to define static values. It will override any `example` value set for the property.

```
definitions:
  Pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: doggie
        x-example: Fido
      tag:
        type: string
```

With the above configuration, x-mock will return a response like the following.

```
{
  "id": -2124524682215424,
  "name": "Fido",
  "tag": "JxCtjRrQml"
}
```
Note that in the above example response x-mock has returned our `x-example` value of "Fido" instead of the `example` value of "doggie" for the `name` field. x-mock is still just using the schema `type` value to random random values for both the id and tag fields. Let's tighten up that response a bit.

### x-mock

The namesake `x-mock` extension provides a meta programing interface to [Chance.js](http://chancejs.com), a sweet random data generator. Chance.js `mixins` can be optionally passed into an x-mock instance to create custom mocking functions. 

The x-mock object includes the following child elements.

#### function

The function field of the x-mock extension is used to name the Chance.js function to use. Here's an example:

```
definitions:
  Pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
        x-mock:
          function: natural
      name:
        type: string
        example: doggie
        x-example: Fido
      tag:
        type: string
```

The Chance.js library has a function [natural](http://chancejs.com/#natural) that will produce a random unsigned integer like so.


```
{
  "id": 8896932646748160,
  "name": "Fido",
  "tag": "egCCrOuL"
}
``` 

This is a good thing because we don't want signed integers for the id field. However maybe we know that the id field should always be from 1 to 9999. Since Chance.js can take an object as configuration we can pass that into the "options" field.

#### options

x-mock `options` provides a way to pass a configuration object to a Chance.js function. Since the [natural](http://chancejs.com/#natural) function can take a config object with both "min" and "max" values let's go ahead and pass that in.


```
definitions:
  Pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
        x-mock:
          function: natural
          options:
            min: 1
            max: 9999
      name:
        type: string
        example: doggie
        x-example: Fido
      tag:
        type: string
```

The `x-mock` object parses to `Chance.natural({min: 1, max: 9999})` and gives us the following response.

```
{
  "id": 2722,
  "name": "Fido",
  "tag": "utW"
}
```

Now the response will always come back with "Fido" as the name and a random natural number between 1 and 9999.

## Mixins

Chance `mixins` are wicked cool so x-mock exposes them. Let's use a mixin to polish up that fugly dog tag. Here's how you pass in a mixin and use it.

Suppose you want to cycle between a few different tags. We could just add an enum to the schema but that would be too easy and besides, maybe the specification is just for a string value. Yo, Dawg. I heard you like Chance.js so let's create a new Chance.js function with an existing Chance.js function.

```javascript
const Xmock = require('x-mock');
const Chance = require('chance').Chance();

const Mixins = [
        {
            'petTag': function () {
                return Chance.pickone([
                    'dog', 
                    'cat', 
                    'friendly', 
                    'hippo', 
                    'dangerous'
                    ]);
            }
        }
    ]
    
    let xmock = Xmock(apiPath, { 'mixins': Mixins });
```

Now we can use the `x-mock` function in our OAS.

```
definitions:
  Pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
        x-mock:
          function: natural
          options:
            min: 1
            max: 9999
      name:
        type: string
        example: doggie
        x-example: Fido
      tag:
        type: string
        x-mock:
          function: petTag
```

Now you should get something like the following.

```
{
  "id": 2722,
  "name": "Fido",
  "tag": "hippo"
}
```

Noice! To be continued...