Skip to content

A CLI to mock with meaningful data a REST API from a Swagger file


Notifications You must be signed in to change notification settings


Repository files navigation


Cause nobody aint got time to wait for back-ends to be developped.


  • A sweet all-in-CLI with no knowledge of Javascript necessary (if you can write JSON you good 👍 )
  • Mocks any object, array or field declared in a swagger with meaningful autogenerated data
  • Persists route mocks to allow you to develop your front-end as fast as a lightning
  • Uses Faker generators behind the curtains
  • Empty responses, error codes, any http method, any body not sure about that last one but I'm trying ok
  • Two lines install and minimal knowledge of backend necessary
  • Supports JSON and YAML swaggers
  • Supports (a big part of) OpenAPI 3.0


  • Ensure that you have both docker and docker-compose installed and available to your terminal.

  • Also, make sure that the docker daemon is running.

  • Now just go for it: npm i -g morphlingjs it takes a while so grab a cub of coffee on the way.

  • Run the configuration utility to select the port morphling will run on: morphling config

  • Add a swagger.yml file to Morphling by doing a morphling apply your/file

Now morphling knows your swagger and can mock it properly. Just try to hit a route that is described in your swagger !

To see what swaggers Morphling knows do a morphling list.

Note: If having any issues during the install with npm such as 'Cannot read property 0 of undefined', try to downgrade your current npm install to 5.2.0

Overriding a route

Morphling allows you to create a mock for a specific route ; because sometimes you need a specific body from your server.

For instance, you want your local server to return a specific response on a given route. It can be a route that is described in your swagger where you don't want autogenerated data or just a route you don't want to bother putting in the swagger.

You will want to use an override file, which you can find two examples of in the examples.

Doing a

  • morphling apply swagger-override-examples/demo.json -o

and then

  • morphling toggle demo.json

will create a route on localhost:8883/v2/store/order/1 and then enable it (if morphling runs on 8883). This route will return, as seen in the example file, a 200 (OK) HTTP code, with an empty body.

CLI Commands

Any command here can be run with the --help flag to give you a tad more info 👍


  • help [cmd] display help for [cmd]

Displays the help


apply|a <file> Apply a Swagger to morphling

Send a Swagger file to the Morphling instance for it to be mocked.

If used with -o flag, save file as an Override file to Morphling. Overrides are disabled by default. To enable/disable them, check the toggle command.

There is no validation working on the server at the time of writing this which means that it will break silently. If a route is not mocked, I suggest that you morphling bash into the instance and run pm2 logs while trying to apply the swagger. Might give you some info. If not, please send an issue! I'll do my best to fix it ASAP.


  • bash|b Bash into the morphling container

Open a bash straight into the container. Useful for checking logs with pm2 logs for instance.


  • config|c Configure the morphling server

Persist CLI options, for instance the port that the CLI will hit on localhost


  • describe|d <filename> Describe a morphling override

Describe an override file's content.


  • list|ls List files saved in morphling

List all swaggers saved to Morphling. Use with -o to list override files.


  • remove|rm Remove a Swagger file saved in Morphling


  • remove-all|rma Clear Swagger files saved in Morphling


  • restart|rr Restart the morphling server

Restart the Morphling instance. who would have thought


  • start|s Start the morphling server on 8883 if no port is provided

Start the morphling instance.


  • stop|k Stop the morphling server\

Stop the morphling instance.


  • toggle|t <filename> Toggle an override

Enable/disable an override. Use with -d to disable all, or -e to enable all.

Note: if you think about other useful commands, feel free to submit an issue! 😉

Installation from source

Here be dragons, you probably don't need to do this, except if want to contribute, which would be lovely.

Ensure that you have both docker and docker-compose installed and available to your terminal.

  • Clone the package
  • Inside the package: make start and wait for the build to be over
  • If the message Morphling started on 8883 pops, it means that everything went well!
  • npm link to make morphling available globally to your terminal
  • morphling config and go through the short process
  • morphling --help for other informations should help you out.

Note: If having any issues during the install with npm such as 'Cannot read property 0 of undefined', try to downgrade your current npm install to 5.2.0

Useful development commands

I've made available a morphling bash command which immediately bashes you inside the currently-running Docker instance of Morphling


  • start Run the build proces and start the Morphling docker instance immediatly then pipe the logs
  • dev Start the server without docker on a bare Nodejs process
  • build Build all javascript files with Babel.
  • docker-build Run the docker build process and run the server.
  • clear-docker Hard-delete the Morphling instance from your local Docker
  • devstart-hard Clear all dependencies and docker Morphling instances and start

Upcoming features feel free to submit PRs

  • SwaggerUI!
  • Print proper Morphlingjs version with --version / -v
  • On the go switching of running ports
  • Add ID to overrides and Swagger files so you dont have to type them down / or maybe just autocomplete them
  • morphling validate A proper validator for the swagger files and an associated CLI command
  • morphling remove Remove a file from Morphling
  • morphling remove-all Remove all files from Morphling (also remove local saves of fixtures) always with --force
  • A better autocompletion using the npm package commander-completion
  • Overriding a field key in an object with a specific faker generator (ie: zipcode, username...)
  • Override checker (ensure that a specific override does not already exist when adding another one)