openapi-mock-server

OpenAPI Mock Server

openapi-mock-server is tool to run a mock implementation of your API locally based on an OpenAPI (swagger ) spec.

Getting Started

Download the binary for your OS: Download. Remember to update your $PATH.

$ openapi-mock-server --help
usage: openapi-mock-server [<flags>] <openapi-spec>

Flags:
  --help              Show context-sensitive help (also try --help-long and --help-man).
  --host="127.0.0.1"  the host or ip address that the server should listen on.
  --port=8000         the port that the server should listen on.
  --overlay=""        path to an overlay.yaml file.
  --base-path=""      override the basePath defined in the spec. defaults to the value defined in the spec.

Args:
  <openapi-spec>  the path to an openapi spec yaml file

To run the server on localhost:8000 use:

openapi-mock-server ./my/openapi-spec.yaml

You can then make requests against endpoints defined in your spec and the server will return automatically generated responses.

The --overlay <overlay.yaml> flag can be used to provide specific response values for an endpoint. The format matches is similar to the OpenAPI format.

For example:

# openapi-spec.yaml
paths:
  /my/endpoint/:
    get:
      operationId: endpoint
      responses:
        200:
          schema:
            type: object
            properties:
              id:
                type: string
              name:
                type: string

# overlay.yaml
paths:
  /my/endpoint/:
    get:
      responses:
        200:
          content: |
            {
              "name": "Specific Name"
            }

The overlay content will be merged with the autogenerated response.

$ curl localhost:8000/my/endpoint/
{
  "id": 76,
  "name": "Specific Name"
}

The overlay will match URL paths including parameters as well. For example:

# openapi-spec.yaml
paths:
  /users/:id/:
    get:
      ...

# overlay.yaml
paths:
  /users/1/:
    get:
      responses:
        200:
          content: ...

Using the above overlay allows you to customize the autogenerated response for /users/1/ without changing the response for the general /users/:id/ endpoint.

warning this software is v0 and it's likely the overlay.yaml file format will change between releases as new usecases and pitfalls are found.