openapi-mock-express-middleware
v4.3.1
Published
Generates express mock-servers from OpenAPI specs
Downloads
6,098
Maintainers
Readme
openapi-mock-express-middleware
Generates express mock-servers from Open API 3.0 specs.
Installation
To begin, you'll need to install openapi-mock-express-middleware
:
$ npm install openapi-mock-express-middleware --save-dev
Usage
Simple Config
const express = require('express');
const { createMockMiddleware } = require('openapi-mock-express-middleware');
const app = express();
app.use(
'/api', // root path for the mock server
createMockMiddleware({ spec: '/absolute/path/to/your/openapi/spec.yml' }),
);
app.listen(80, () => console.log('Server listening on port 80'));
Advanced Config
The middleware uses json-schmea-faker under the hood. To configure it, you can pass the options object to the factory function. (The full list of available options can be seen here)
const express = require('express');
const { createMockMiddleware } = require('openapi-mock-express-middleware');
const app = express();
app.use(
'/api',
createMockMiddleware({
spec: '/absolute/path/to/your/openapi/spec.yml', // string or OpenAPIV3.Document object
options: { // json-schema-faker options
alwaysFakeOptionals: true,
useExamplesValue: true,
randomizeExamples: true, // choose a random example from the examples object; when set to false (default) the first example is used
// ...
},
configure: (jsf) => {
// function where you can extend json-schema-faker
...
}
}),
);
app.listen(80, () => console.log('Server listening on port 80'));
Mock data
Basic behavior
By default midleware generates random responses depending on the types specified in the openapi docs.
doc.yml
...
paths:
/company
get:
responses:
'200':
content:
application/json:
schema:
type: object
required:
- id
- number
properties:
id:
type: string
number:
type: integer
...
GET /company response
{
id: 'dolor veniam consequat laborum',
number: 68385409.
}
Faker or Chance generated responses
In addition faker.js
or chance.js
methods can be specified for data generation. In order to use these generators you have to configure middleware through the configure
option of the factory function.
const express = require('express');
const { createMockMiddleware } = require('openapi-mock-express-middleware');
import faker from '@faker-js/faker';
import Chance from 'chance';
const app = express();
app.use(
'/api',
createMockMiddleware({
spec: '/absolute/path/to/your/openapi/spec.yml',
configure: (jsf) => {
jsf.extend('faker', () => faker);
jsf.extend('chance', () => new Chance());
}
}),
);
app.listen(80, () => console.log('Server listening on port 80'));
After that you can use 'x-faker' and/or 'x-chance' attributes in your openapi specs.
spec.yml
...
paths:
/user
get:
responses:
'200':
content:
application/json:
schema:
type: object
required:
- id
- name
properties:
id:
type: string
x-faker: random.uuid
name:
type: string
x-faker: name.findName
email:
type: string
x-chance:
email:
domain: fake.com
...
GET /user response
{
id: '8c4a4ed2-efba-4913-9604-19a27f36f322',
name: 'Mr. Braxton Dickens',
email: '[email protected]'
}
Responses generated from examples
If an example for the response object is specified, it will be used as a resulting sever response.
doc.yml
...
paths:
/user
get:
responses:
'200':
content:
application/json:
schema:
type: object
example:
id: 'id-125'
name: 'John Smith'
required:
- id
- name
properties:
id:
type: string
x-faker: random.uuid
name:
type: string
x-faker: name.findName
...
GET /user response
{
id: 'id-125',
name: 'John Smith'.
}
If multiple examples for the response object are specified, the first one will be used as a resulting sever response.
doc.yml
...
paths:
/user
get:
responses:
'200':
content:
application/json:
schema:
type: object
examples:
first:
value:
id: 'id-125'
name: 'John Smith'
second:
value:
id: 'some-other-id'
name: 'Joe Doe'
required:
- id
- name
properties:
id:
type: string
x-faker: random.uuid
name:
type: string
x-faker: name.findName
...
GET /user response
{
id: 'id-125',
name: 'John Smith'.
}
If you want to use some other logic for generating responses from the examples
attributes you can easily implement it by overwriting this behavior in the configure
option of the middleware's factory function:
const express = require('express');
const { createMockMiddleware } = require('openapi-mock-express-middleware');
const app = express();
app.use(
'/api',
createMockMiddleware({
spec: '/absolute/path/to/your/openapi/spec.yml',
configure: (jsf) => {
jsf.define('examples', (value) => {
if (typeof value === 'object' && value !== null && Object.keys(value).length) {
return value[Object.keys(value)[0]].value;
}
return '';
});
}
}),
);
app.listen(80, () => console.log('Server listening on port 80'));
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.