openapi-mock-express-middleware

openapi-mock-express-middleware

Generates an express mock server from an Open API 3.0 documentation.

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 locale and 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
    locale: 'ru', // json-schema-faker locale, default to 'en'
    options: { // json-schema-faker options
      alwaysFakeOptionals: true,
      useExamplesValue: true,
      // ...
    },
    jsfCallback: (jsf, faker) => {
    	// 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 generated responses

In addition faker functions can be specified for data generation. The list of all available function can be found in the faker documentation.

doc.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
...

GET /user response

{
  id: '8c4a4ed2-efba-4913-9604-19a27f36f322',
  name: 'Mr. Braxton Dickens'.
}

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'.
}

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT