openapi-mocker

Create a mock server from an OpenAPI 3.0 specification.

Installation

• Install with cargo:

cargo install openapi-mocker

Usage

1. Create an OpenAPI 3.0 specification file. For example, openapi.yaml:

   openapi: 3.0.0info:
   title: Example APIversion: 1.0.0paths:
   /hello:
   get:
   responses:
   '200':
   description: OKcontent:
   application/json:
   schema:
   type: objectproperties:
   message:
   type: stringexamples:
   default:
   value:
   message: Hello, world!'400':
   description: Bad Requestcontent:
   application/json:
   schema:
   type: objectproperties:
   message:
   type: stringexamples:
   default:
   value:
   message: Bad request

2. Run the mock server:

   openapi-mocker openapi.yaml

   • Or, Run with docker:

   docker run \
   -v $(pwd)/tests/testdata/petstore.yaml:/openapi.yaml \
   -p 8080:8080 \
   thisk8brd/openapi-mocker:latest \
   /openapi.yaml

3. Perform an http request to the mock server:

   curl -i http://localhost:8080/hello

   The response should be: json {"message":"Hello, world!"}

   Requesting non existent route

   curl -i http://localhost:8080/does-not-exist

   The response should be 404 Not Found.

Options

• --port or -p: Port to run the server on. Default is 8080.

Performing requests

You can use custom examples defined in the OpenAPI specification to test different responses. Custom examples can be defined and requested in different ways.

Requesting by path

You can define an example with the exact path you want to match. Example:

openapi: 3.0.0info:
title: Example APIversion: 1.0.0paths:
/hello/{name}:
get:
responses:
'200':
description: OKcontent:
application/json:
schema:
type: objectproperties:
message:
type: stringexamples:
default:
value:
message: Hello, world!/hello/jon_snow:
value:
message: You know nothing, Jon Snow!

Request the example by the exact path:

curl -i http://localhost:8080/hello/jon_snow

The response should be:

{"message":"You know nothing, Jon Snow!"}

Request the default example:

curl -i http://localhost:8080/hello/arya_stark

The response should be:

{"message":"Hello, world!"}

Requesting by query parameter

You can define an example with a query parameter you want to match.

Example:

openapi: 3.0.0info:
title: Example APIversion: 1.0.0paths:
/hello:
get:
parameters:
- name: namein: queryrequired: trueschema:
type: stringresponses:
'200':
description: OKcontent:
application/json:
schema:
type: objectproperties:
message:
type: stringexamples:
default:
value:
message: Hello, world!"query:name=sansa":
value:
message: Sansa Stark

Request the example by the query parameter:

curl -i http://localhost:8080/hello?name=sansa

The response should be:

{"message": "Sansa Stark"}

Request that does not match the query parameter:

curl -i http://localhost:8080/hello?name=arya

The response should be:

{"message": "Hello, world!"}

Requesting by headers

You can define an example with a header you want to match.

Example:

openapi: 3.0.0info:
title: Example APIversion: 1.0.0paths:
/hello:
get:
parameters:
- name: namein: headerrequired: trueschema:
type: stringresponses:
'200':
description: OKcontent:
application/json:
schema:
type: objectproperties:
message:
type: stringexamples:
default:
value:
message: Hello, world!"header:x-name=tyrion":
value:
message: Tyrion Lannister

Request the example by the header:

curl -i http://localhost:8080/hello -H "x-name: tyrion"

The response should be:

{"message": "Tyrion Lannister"}

Request that does not match the header:

curl -i http://localhost:8080/hello

The response should be:

{"message": "Hello, world!"}

Note: The matches occur in the following order: path, query, headers. It is also important to note that the request is going to return the first match found in the order above. If no match is found, the default example is going to be returned.

Note: The matches are applied accross all the examples and responses in the OpenAPI specification.

Contributing

Contributions are welcome! Please see the contributing guidelines.

License

MIT