leboncoin / morphlingjs

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

Morphling

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

Features

• 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

Installation

• 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

• help [cmd] display help for [cmd]

Displays the help

apply

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

• bash|b Bash into the morphling container

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

config

• config|c Configure the morphling server

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

describe

• describe|d <filename> Describe a morphling override

Describe an override file's content.

list

• list|ls List files saved in morphling

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

remove - NOT IMPLEMENTED YET

• remove|rm Remove a Swagger file saved in Morphling

remove-all - NOT IMPLEMENTED YET

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

restart

• restart|rr Restart the morphling server

Restart the Morphling instance. who would have thought

start

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

Start the morphling instance.

stop

• stop|k Stop the morphling server\

Stop the morphling instance.

toggle

• 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

make

• 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)

morphlingjs's Issues

Responds with the actual schema instead of faked array of objects

Querying curl localhost:8883/persons using following Open API 2 document:

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https

host: simple.api
basePath: /


paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

it responds with this body:

[
	{
		"type": "object",
		"required": [
			"username"
		],
		"properties": {
			"firstName": {
				"type": "string"
			},
			"lastName": {
				"type": "string"
			},
			"username": {
				"type": "string"
			}
		}
	},
	{
		"type": "object",
		"required": [
			"username"
		],
		"properties": {
			"firstName": {
				"type": "string"
			},
			"lastName": {
				"type": "string"
			},
			"username": {
				"type": "string"
			}
		}
	},
	{
		"type": "object",
		"required": [
			"username"
		],
		"properties": {
			"firstName": {
				"type": "string"
			},
			"lastName": {
				"type": "string"
			},
			"username": {
				"type": "string"
			}
		}
	},
	{
		"type": "object",
		"required": [
			"username"
		],
		"properties": {
			"firstName": {
				"type": "string"
			},
			"lastName": {
				"type": "string"
			},
			"username": {
				"type": "string"
			}
		}
	},
	{
		"type": "object",
		"required": [
			"username"
		],
		"properties": {
			"firstName": {
				"type": "string"
			},
			"lastName": {
				"type": "string"
			},
			"username": {
				"type": "string"
			}
		}
	}
]

Error: [email protected] postinstall: `NODE_PORT=1 docker-compose build`

Hi there,
I'd be very interested in trying this tool out but when i run npm i -g morphlingjs I get an error stating that postinstall failed. I haven't used docker before so it could be also that.

Here's npm log:

24100 error Windows_NT 10.0.15063
24101 error argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "i" "-g" "morphlingjs"
24102 error node v6.10.3
24103 error npm  v3.10.10
24104 error code ELIFECYCLE
24105 error [email protected] postinstall: `NODE_PORT=1 docker-compose build`
24105 error Exit status 1
24106 error Failed at the [email protected] postinstall script 'NODE_PORT=1 docker-compose build'.
24106 error Make sure you have the latest version of node.js and npm installed.
24106 error If you do, this is most likely a problem with the morphlingjs package,
24106 error not with npm itself.
24106 error Tell the author that this fails on your system:
24106 error     NODE_PORT=1 docker-compose build
24106 error You can get information on how to open an issue for this project with:
24106 error     npm bugs morphlingjs
24106 error Or if that isn't available, you can get their info via:
24106 error     npm owner ls morphlingjs
24106 error There is likely additional logging output above.
24107 verbose exit [ 1, true ]

Replace `make` and `makefile` with Grunt or Gulp

I'd suggest using one of the Node.js ecosystem native task runners instead of the hardcore unix make in order to make the codebase more contribution friendly.

Even if not using the JS API of the build components (Babel) and just using the CLI I'd suggest using for instance grunt-exec

Unhandled Stream error in pipe

trying to apply a test swagger.json gives me Unhandled stream error in pipe. I tested it as valid json so I'm not sure?

github doesn't support json or i'd upload it. lol

Remove Docker requirement for `npm install`

Let's make it CI friendly. They're imo right here

What about starting a dettached server instead of Docker?

morphling start -d

"Not Found" response when adding my own swagger

Hello,

I installed morphling globally and tested it with supplied example swaggers, everything works fine. :)
Then I added my own swagger and now I get a "Not Found" on every URL that worked before (except for overrided pattern which still works very well). There wasn't any error while applying my new swagger.

NB : if you need my own swagger file I can send it to you via email (because it's quite confidential). ;)

Thanks in advance.

Wrong version printed

Hello,
When I do morphling --version , I always get 0.0.1 also I installed [email protected]
;)

Enable Error case 4XX

Being able to choose 4XX answer fot any route

Crashing on in-line `schema`, moving under `definitions` resolves it

The Error

$ morphling bash
Container ID is:
584d6828db74
Bashing into Morphling.. Type exit to exit.
root@584d6828db74:/usr/app# pm2 log
[TAILING] Tailing last 15 lines for [all] processes (change the value with --lines option)
  0|server  | Error in getDB TypeError: Cannot read property 'replace' of undefined
  0|server  |     at getReferencesAndCount (/usr/app/src/utils/createRouterFromSwagger.js:189:46)
  0|server  |     at /usr/app/src/utils/createRouterFromSwagger.js:125:29
  0|server  |     at dispatch (/usr/app/node_modules/koa-router/node_modules/koa-compose/index.js:44:32)
  0|server  |     at next (/usr/app/node_modules/koa-router/node_modules/koa-compose/index.js:45:18)
  0|server  |     at /usr/app/node_modules/koa-router/lib/router.js:345:16
  0|server  |     at dispatch (/usr/app/node_modules/koa-router/node_modules/koa-compose/index.js:44:32)
  0|server  |     at /usr/app/node_modules/koa-router/node_modules/koa-compose/index.js:36:12
  0|server  |     at dispatch (/usr/app/node_modules/koa-router/lib/router.js:350:31)
  0|server  |     at dispatch (/usr/app/node_modules/koa-compose/index.js:42:32)
  0|server  |     at dispatch (/usr/app/node_modules/koa-router/lib/router.js:332:32)
  0|server  | (node:17) [DEP0013] DeprecationWarning: Calling an asynchronous function without callback is deprecated.

The OpenAPI 2 document

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https

host: simple.api
basePath: /


paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string