@tempworkssoftware/open-api-mocker NPM

Open API Mocker

Generate mock data for your application in a way that is maintainable and responsive to a changing API.

This library will consume one or more Open API 2.0 definitions, and then you can call the fetchMock function to generate a mock response for a given request.
The mock data will include random values from the Chance library. The random values will be generated based on a hash of the request. This means that if you make the same request more than once, you will receive the same response.
The structure of the mock data will conform to the provided Open API schema by default. If you'd like to make the data even more realistic, you can customize the constraints for how the mock responses are generated on a per-endpoint basis, or for all operations in an API at once.

Installation

npm install --save-dev @tempworkssoftware/open-api-mocker

Requirements

This library was written to support a product that uses the Open API 2.0 format, and is currently limited to that specification. In addition, each operation in an API definition must have a unique operationId, because it will be used as a variable name and as a folder name.

Usage

`generateDescriptions`

This library supports per-endpoint mock customization. This is made possible by generating files for each API operation that describe how to mock its response. To begin, call the generateDescriptions function from a Node environment:

const oam = require('@tempworkssoftware/open-api-mocker');

await oam.generateDescriptions({
    apiDefinition: 'https://my-api.com/swagger.json', // Can be a URL, file path, or object
    outputPath: path.resolve(__dirname, 'myApiMocks'), // Where to put the mock response descriptions
});

This will produce the following file structure:

myApiMocks
│
└───GetProduct
│      defaultMockResponse_DONT_EDIT.json
│      extendMockResponse.js
│
└───PostProduct
│      defaultMockResponse_DONT_EDIT.json
│      extendMockResponse.js
│
└─── ...etc

There will be a folder for each API operation, containing two files. These two files together describe how to generate a mock response for the operation.

`defaultMockResponse_DONT_EDIT.json`

Here is a simple example file:

{
    "status": 200,
    "bodySchema": {
        "type": "object",
        "properties": {
            "productId": {
                "format": "int32",
                "type": "integer",
                "valueOfParameter": "productId"
            },
            "productName": {
                "type": "string"
            },
            "description": {
                "type": "string",
                "chance": "sentence"
            }
        }
    }
}

This file describes the structure of a successful response to this operation. It uses JSON Schema format, but allows some additional properties which can further constrain how this mock response will be generated.
This file will be updated every time generateDescriptions is run, so you should not edit this file directly. If you would like to customize how this file is generated, you can do it in a way that will affect all operations in the API: Use the getDefaultMockRules callback that you can include in the options passed to generateDescriptions.

`extendMockResponse.js`

Here is a simple example file:

/**
 * Function for manually describing mock data for the following API operation:
 * OperationId: GetProduct
 * HTTP Method: GET
 * Path: /products/{productId}
 *
 * @type {import('@tempworkssoftware/open-api-mocker').ExtendMockResponse}
 */
// eslint-disable-next-line no-unused-vars
const extendMockResponse = (parameters, utils) => {
    return {
        partialBody: {
            productName: 'Chocolate Frog',
        },
    };
};

export default extendMockResponse;

This file will not be overwritten when generateDescriptions is run, so feel free to edit it yourself. This file is your chance to customize the mock response in a way that will only affect this endpoint.
The function in this file will be called at runtime when processing a request for the API operation. Within this function, you have access to the operation parameters from the request.
You have various options for how to describe the response body in your return value:
- partialBody: The values you define here will be deeply merged with the the values generated from the bodySchema in defaultMockResponse_DONT_EDIT.json when generating the mock response.
- bodySchema: The partial schema you define here will be deeply merged with the bodySchema in defaultMockResponse_DONT_EDIT.json before generating the mock response.
- body: The actual response body returned for the request. If this is provided, bodySchema is ignored and body is used instead. Of course, using body will result in no randomness in the mock response.

Example Mock Response

If the two example files above were used for the request 'GET /products/14', then the generated mock response might be:

{
    status: 200,
    body: {
        productId: 14,
        productName: 'Chocolate Frog',
        description: 'Witpevze mappos isoletu fo res bi geow pofin mu rupoho revzi utva ne.',
    }
}

`configure`

Once all of the mock description files have been generated, you'll want to configure open-api-mocker for runtime operation. You'll want to do this once, before fetchMock is called. At the least, you'll need to tell open-api-mocker where your mock response description files are. When you ran generateDescriptions, a file named mockIndex.js should have been created in your output directory. All you need to do is import that and pass it through to the configure function:

import oam from '@tempworkssoftware/open-api-mocker';
import mockApiIndex from './myApiMocks/mockIndex';

oam.configure({
    generatedMockApis: [
        {
            generatedMockApi: mockApiIndex,
        },
    ],
});

Note that if this will be run in the context of a browser, you will want to import from @tempworkssoftware/open-api-mocker/dist/browser.
There are a few more settings that you may find useful here. In particular, we needed the useCaseSensitivePathAndParameterMatching option.

`fetchMock`

Once all of the mock description files have been generated and you've told open-api-mocker where to find them, you can make use of the fetchMock function to generate a mock response for a given request.

Note that if this will be run in the context of a browser, you will want to import from @tempworkssoftware/open-api-mocker/dist/browser.
Note that if a mock response isn't found, undefined will be returned. This gives you the flexibility to fall back however you deem appropriate.

import { fetchMock } from '@tempworkssoftware/open-api-mocker';

const mockResponse = await fetchMock('https://my-api.com/products/14');

Runtime mock overrides

You can programmatically override a mock for an operation. This is especially useful for making assertions about specific data within a test.

import { mock, resetMock, fetchMock } from '@tempworkssoftware/open-api-mocker';

mock('GetProduct', {
    productId: 9,
    productName: 'Licorice Wand',
    description: 'A wand made of licorice.',
});

const mockResponse = await fetchMock('https://my-api.com/products/14');
const mockResponseBody = await mockResponse.json();
// mockResponseBody:
// {
//     productId: 9,
//     productName: 'Licorice Wand',
//     description: 'A wand made of licorice.'
// }

resetMock('GetProduct');

You can also partially override an operation mock from within a test. The values of the partialMock will be deeply merged with the values generated from the mock response description files.

import { mock, resetMock, fetchMock } from '@tempworkssoftware/open-api-mocker';

partialMock('GetProduct', {
    productName: 'Licorice Wand',
});

const mockResponse = await fetchMock('https://my-api.com/products/14');
const mockResponseBody = await mockResponse.json();
// mockResponseBody:
// {
//     productId: 14,
//     productName: 'Licorice Wand',
//     description: 'Witpevze mappos isoletu fo res bi geow pofin mu rupoho revzi utva ne.',
// }

resetMock('GetProduct');