@soluzioni-futura/openapi-mock-server
v0.5.1
Published
OpenAPI Mock Server
Downloads
4
Readme
openapi-mock-server
openapi-mock-server
is an easy to use CLI program to create mock servers from an OpenAPI Specification.
This module is built on top of express-openapi-validator and use json-schema-faker to generate random responses to HTTP requests.
Fully supports circular $ref pointer in the OpenAPI Specification.
Installation
This is a Node.js module available through the npm registry.
Installation is done using the npm install
command:
$ npm install -g @soluzioni-futura/openapi-mock-server
Quick start
Install openapi-mock-server
globally
$ npm install -g @soluzioni-futura/openapi-mock-server
Start the mock server
$ mock --openapi "path or URL to the OpenAPI Specification"
# or run the mock server in debug mode
$ DEBUG=mock* mock --openapi "path or URL to the OpenAPI Specification"
Command line flags
Many options have command line equivalents. In those cases, any arguments passed here will override the config file, if you're using one. This is a list of all supported options:
--openapi path or URL to the OpenAPI Specification
--port mock server port (default 8080)
--mock-config path to mock server config file
(default mock-config.(ts, js, json))
--mock-overrides path to mock server overrides config file
(default mock-overrides.(ts, js, json))
--express.validateRequests determines whether the validator should validate
requests (default false)
--express.validateResponses determines whether the validator should validate
responses (default false)
--express.unknownFormats defines how the validator should behave if an unknown
or custom format is encountered (default "ignore")
--jsf.fillProperties if enabled, it will try to generate missing properties
to fulfill the schema definition (default: false)
--jsf.useExamplesValue if enabled, it will return a random value from examples
if they're present (default: true)
--jsf.useDefaultValue if enabled, it will return the default value if present
(default: true)
--jsf.failOnInvalidFormat if enabled, it will throw an Error for unknown formats
(default: false)
--cors.origin configures the Access-Control-Allow-Origin CORS header
(default: "*")
--cors.credentials configures the Access-Control-Allow-Credentials CORS header.
Set to true to pass the header, otherwise it is omitted.
(default: true)
Configuration files
openapi-mock-server
accepts two types of configuration files:
- a mock server config file
- a mock server overrides config file
Mock server config file
By default
openapi-mock-server
will try to import the filesmock-config
(.ts, .js, .json) from the current directoryprocess.cwd()
. The first successful import will be used.
You can specify the path of this file via CLI flag --mock-config
$ mock --mock-config path/to/file
This file is used to configure express and json-schema-faker of the mock server, it's divided into three sections:
express
contains express configurable options. json schema | about express-openapi-validator options (not all options are supported, see the json schema to see which ones are supported)jsf
contains json-schema-faker configurable options. json schema | about jsf optionscors
contains cors configurable options. cors schema | about cors options (not all options are supported, see the json schema to see which ones are supported)
// example
{
"express": {
"port": 9090,
"openapi": "path/or/URL/to/OpenAPI/Specification"
},
"jsf": {
"failOnInvalidFormat": true
},
"cors": {
"origin": "http://localhost:3000"
}
}
Mock server overrides config file
By default
openapi-mock-server
will try to import the filesmock-overrides
(.ts, .js, .json) from the current directoryprocess.cwd()
. The first successful import will be used.
You can specify the path of this file via CLI flag --mock-overrides
$ mock --mock-overrides path/to/file
This file able you to override the mock server behavior to particular http requests json schema.
If an override of a path is provided that it will be used instead of the random response. Only statusCode: 200
is supported for now.
Consider splitting this file into multiple ones because one single large mock-overrides file is not maintainable. Recursive import mock-overrides files
// example
{
"routes": [
{
"request": {
"path": "path/to/override",
"method": "get"
},
"responses": [
{
"statusCode": 200,
"headers": {
// response header
},
"body": {
// response body
}
}
]
}
]
}
Recursive import mock-overrides files
Customize mock server responses via mock-overrides files is a very convenient way when you do not have an up and running backend or simply you are testing an edge case (es. API that requires auth, a key match with an object in S3).
The mock-overrides file can become very long and hard to maintain, in order to solve this issue we introduced a way to import partial files instead of a single one.
To achieve this feature we used glob, so instead of passing a file path you can specify a pattern and the mock server will automatically merge all those files. The schema of those files follows the convention specified above.
Example of recursive import mock-overrides files
Let's say that you want to split the mock-overrides file into 2 files:
- mock/mock-overrides-1.json
- mock/mock-overrides-2.json
// mock/mock-overrides-1.json
{
"routes": [
{
"request": {
"path": "path/to/override/1",
"method": "get"
},
"responses": [
{
"statusCode": 200,
"headers": {
// response header
},
"body": {
// response body
}
}
]
}
]
}
// mock/mock-overrides-2.json
{
"routes": [
{
"request": {
"path": "path/to/override/2",
"method": "get"
},
"responses": [
{
"statusCode": 200,
"headers": {
// response header
},
"body": {
// response body
}
}
]
}, {
"request": {
"path": "path/to/override/3",
"method": "get"
},
"responses": [
{
"statusCode": 200,
"headers": {
// response header
},
"body": {
// response body
}
}
]
}
]
}
Now, to run the mock server that uses those 2 files (NOTE: both into the folder mock
)
mock --mock-overrides "./path/to/mock/folder/*.json"
Remember to wrap the pattern with "
With NodeJS or TypeScript
It's possible to launch the mock server via a JS or TS script. It's an awesome way when you want to generate mock-overrides via scripts.
The MockServer
function exported accepts an object with 4 properties:
mockConfigPath?: string
path to mock-config filemockOverridesPath?: string
path to mock-overrides filemockServerConfig?: MockServerConfigType
mock-config object, if provided will overwrite default and mockConfigPath valuesmockOverrides?: MockOverrides
mock-overrides object, if provided it will be used and any other files will be ignored
NOTE: the MockServer will still try to require the defaults files if no path is provided (mock-config file, mock-overrides file).
// example
const MockServer = require("@soluzioni-futura/openapi-mock-server")
const options = {
mockConfigPath: "...",
mockOverridesPath: "...",
mockServerConfig: {
express: {
openapi: "..."
}
},
mockOverrides: {
routes: [
...
]
}
}
MockServer(options)
Developer instructions
In order to work with this project you need:
Before you start developing you must prepare the environment
$ git clone https://github.com/soluzionifutura/openapi-mock-server.git
$ cd openapi-mock-server
$ npm install
To build the solution run
$ npm run build
It will build the solution in the dist/
folder. Thus to try it out
$ npm start
If you just wanna run your changes locally without building the project
$ npm run dev
You may want to pass a CLI flag to the script. npm documentation about "--"
For example:npm run dev -- --port 9090
ornpm start -- --port 9090
NOTE If you change a *.json file in src/schemas
then you must regenerate typescript types running
$ npm run init:types