openapi-mock-express-middleware
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    npm deps Build Status codecov size

    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

    Install

    npm i openapi-mock-express-middleware

    DownloadsWeekly Downloads

    508

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    103 kB

    Total Files

    58

    Last publish

    Collaborators

    • avatar