Easy API testing with Mockoon, Docker and open-api

tl;dr:

docker run -d --mount type=bind,source=<open-api-spec.yaml>,target=/data,readonly -p 3000:3000 --name mockoon mockoon/cli:latest -d data -p 3000

Intro

I came across this handy one liner for mocking APIs using Docker, MockoonCLI and open-api. Assuming you have Docker installed, this is a simple way to generate a mock API interactions without too much hassle.

An example case I was using it for was that I was a developer on project A which when deployed would interact with another project B. Project B however was pretty much a black box to me but I had the open-api spec which was being implemented by Project B. Rather than spending half a day trying to configure Project B and its interactions, I found this handy command and I was able to mock the interactions with Project B pretty thoroughly.

Setup

The Mockoon API works by responding with the example responses in the open-api.yaml (another reason to keep up to date documentation! 😄). Here's a working example using open api's example open-api.yaml file.

We spin up our Mockoon Docker container as below:

docker run -d --mount type=bind,source=./openapi.yaml,target=/data,readonly -p 3000:3000 --name mockoon mockoon/cli:latest -d data -p 3000

GET

We can first explore the GET endpoint using a curl command:

curl http://localhost:3000/api/v3/pet/1

For this endpoint we provide the numerical value of the id of the pet. The id provided is irrelevant to Mockoon. This is handy in the case where we are running integration tests working with random ids. With this command we get the following result:

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    ""
  ],
  "tags": [
    {
      "id": 75776,
      "name": ""
    }
  ],
  "status": "pending"
}

This result is an amalgamation of the individual uses of the example: field in the openapi.yaml file we provided. It is also possible to specify a complete example at the endpoint definition rather than the individual values which provides an easier way of editing the return body to your use case.

PUT

The same can be used for other operations. Let's look at PUT as an example:

curl -X 'PUT'   'http://localhost:3000/api/v3/pet'   -H 'accept: application/json'   -H 'Content-Type: application/json'   -d '{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
'

Again, Mockoon does not validate the input, so we could actually put anything in the json data field. We would still receive the below output which has been generated based on the examples in the openapi.yaml file:

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    ""
  ],
  "tags": [
    {
      "id": 81582,
      "name": ""
    }
  ],
  "status": "pending"
}

Conclusion

This setup provides an easy way of performing automated or manual integration testing without having to rely on an API which can be difficult to setup or maintain. I use it for some quick manual integration testing.