Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jormaechea/open-api-mocker
A mock server based in OpenAPI Specification
https://github.com/jormaechea/open-api-mocker
api api-mocker docker mock mock-server mocking openapi schema schemas
Last synced: 3 days ago
JSON representation
A mock server based in OpenAPI Specification
- Host: GitHub
- URL: https://github.com/jormaechea/open-api-mocker
- Owner: jormaechea
- License: mit
- Created: 2019-06-22T17:38:08.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-11-30T07:34:30.000Z (about 1 year ago)
- Last Synced: 2025-01-14T03:07:00.222Z (10 days ago)
- Topics: api, api-mocker, docker, mock, mock-server, mocking, openapi, schema, schemas
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/open-api-mocker
- Size: 1.23 MB
- Stars: 119
- Watchers: 5
- Forks: 34
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI Mocker
[](https://www.npmjs.com/package/open-api-mocker)
[](https://codeclimate.com/github/jormaechea/open-api-mocker/maintainability)
[](https://codeclimate.com/github/jormaechea/open-api-mocker/test_coverage)
[](https://hub.docker.com/repository/docker/jormaechea/open-api-mocker)
An API mocker based in the OpenAPI 3.0 specification.
## Installation and usage
### Using npm
```
npm i -g open-api-mocker
open-api-mocker -s my-schema.json -w
open-api-mocker --help # To prompt every available setting.
```
### Using docker
```
docker run -v "$PWD/myschema.json:/app/schema.json" -p "5000:5000" jormaechea/open-api-mocker
```
Or to run an specific version
```
docker run -v "$PWD/myschema.json:/app/schema.json" -p "5000:5000" jormaechea/open-api-mocker:X.Y.Z`
```
You can set any parameter when running inside a docker container
```
docker run -v "$PWD/myschema.json:/app/schema.json" -p "3000:3000" jormaechea/open-api-mocker:X.Y.Z -s /app/schema.json -p 3000`
```
## Capabilities
- [x] Read yaml and json OpenAPI v3 schemas.
- [x] Port binding selection
- [x] Request parameters validation
- [x] Request body validation
- [x] Response body and headers generation based on examples or schemas
- [x] Response selection using request header: `Prefer: statusCode=XXX` or `Prefer: example=name`
- [x] Request and response logging
- [x] Servers basepath support
- [x] Support x-faker and x-count extension methods to customise generated responses
- [ ] API Authentication
## Customizing Generated Responses
The OpenAPI specification allows custom properties to be added to an API definition in the form of _x-*_.
OpenAPI Mocker supports the use of two custom extensions to allow data to be randomised which should allow for more
realistic looking data when developing a UI against a mock API for instance.
### x-faker
The _x-faker_ extension is valid for use on properties that have a primitive type (e.g. `string`/`integer`, etc.)
and can be used within an API definition to use one or more methods from the community mantained
[Faker](https://fakerjs.dev/) library for generating random data.
Given the following API definition:
```yaml
openapi: '3.0.2'
info:
title: Cats
version: '1.0'
servers:
- url: https://api.cats.test/v1
paths:
/cat:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
firstName:
type: string
x-faker: person.firstName
lastName:
type: string
x-faker: person.lastName
fullName:
type: string
x-faker: '{{person.firstName}} {{person.lastName}}'
age:
type: string
x-faker: 'number.int({ "min": 1, "max": 20 })'
```
A JSON response similar to the following would be produced:
```JSON
{
"firstName": "Ted",
"lastName": "Kozey",
"fullName": "Herbert Lowe",
"age": 12
}
```
The _x-faker_ extension accepts values in 3 forms:
1. _fakerNamespace.method_. e.g. `string.uuid`
2. _fakerNamespace.method({ "methodArgs": "in", "json": "format" })_. e.g. `number.int({ "max": 100 })`
3. A mustache template string making use of the 2 forms above. e.g. `My name is {{person.firstName}} {{person.lastName}}`
*NOTE*: To avoid new fake data from being generated on every call, up to 10 responses per endpoint are cached
based on the incoming query string, request body and headers.
### x-count
The _x-count_ extension has effect only when used on an `array` type property.
If encountered, OpenAPI Mocker will return an array with the given number of elements instead of the default of an
array with a single item.
For example, the following API definition:
```yaml
openapi: '3.0.2'
info:
title: Cats
version: '1.0'
servers:
- url: https://api.cats.test/v1
paths:
/cat:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
x-count: 5
items:
type: string
```
Will produce the following response:
```JSON
[
"string",
"string",
"string",
"string",
"string"
]
```
## Advanced usage
See the [advanced usage docs](docs/README.md) to extend or build your own app upon OpenAPI Mocker.
## Tests
Simply run `npm t`
## Contributing
Issues and PRs are welcome.