Tutorial 2: Create a service and simulation by importing from a Swagger specification

In this walkthrough you will create a virtual pet store API by uploading a Swagger v2 specification document, that exposes 20 endpoints; of which we will explore 3:

An HTTP GET that returns a pet for a given petId
An HTTP GET that returns an array of pets matching a list of provided statuses
An HTTP POST that creates a new user with the supplied data

Part 1. Upload the Swagger file

Follow these steps:

Download the sample Swagger file to your computer from: https://petstore.swagger.io/v2/swagger.json
Navigate to the Simulations section and click the From Swagger button.
In the subsequent dialogue box name the simulation petstore-swagger-sim, locate the file and click Confirm.
You will be presented with the list of simulations and should see the new simulation at the top of the list. Click the edit button to open the simulation editor.
- Note that this is the master simulation file. Once a new service is started from the main dashboard and this simulation is chosen, the new service will take a copy of this simulation, and any changes made at the service level will not automatically be synchronised with this master version.
From the editor you can see the 20 endpoints imported from the swagger document.
At this point we can spin up a service and this simulation will work.

Part 2. Start a new service with the petstore-swagger-sim

Follow these steps:

Navigate to the main dashboard.
Click on +Add under services.
Select petstore-swagger-sim as the simulation to use.
- Note that if you are part of an organisation and you doing this tutorial alongside other members of the same organisation, you will need to locate the version of the simulation under your name in the drop-down list.
Name the service petstore. This will prefix the URL for your unique service with petstore.
Leave the rest of the defaults as they are and click Confirm.
Once the orange blinking spot turns green, the service is running is can be tested from cURL, a web browser or Postman.
Copy the URL for the service and paste it in a web browser. If you make the request with just the base URL Hoverfly will return a matching error as it was not able to match your request with any the Request/Response pairs it has generated for the simulation from the Swagger file.

Part 3. Test the GET /v2/pet/[^/]+ endpoint

Follow these steps:

Append /v2/pet/10 to the end of the url so that it looks something like this: https://petstore-youraccount.hoverfly.io/v2/pet/10

Hoverfly will match the request to the closest Request matcher it has which is GET/v2/pet/[^/]+ and will return the response it has stored which will be:

{
    "id": 0,
    "category": {
        "id": 0,
        "name": "string"
    },
    "name": "doggie",
    "photoUrls": [
        "string"
    ],
    "tags": [
        {
            "id": 0,
            "name": "string"
        }
    ],
    "status": "available"
}

Part 4. Test the GET /v2/pet/findByStatus endpoint

Follow these steps:

Now we can try another GET which returns an array of pets given a status. This Request matcher requires a path of exactly /v2/pet/findByStatus, and then a query parameter called status with a value. The query should look something like https://petstore-youraccount.hoverfly.io/v2/pet/findByStatus?status=somestatus

When executing this request, the response will be the following:

[
    {
      "id": 0,
      "category": {
        "id": 0,
        "name": "string"
      },
      "name": "doggie",
      "photoUrls": [
        "string"
      ],
      "tags": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "status": "available"
    }
  ]

These canned responses are correct in structure, but may not reflect actual values in the test system. If that is required they can easily be replaced by editing them in the simulation editor for the service.
Navigate to the simulation for the service by going to the dashboard, and then clicking the Simulation named petstore-swagger-sim for the petstore service under the Services section.

Once in the simulation editor, click the "GET/v2/pet/findByStatus" endpoint (it might be on the 2nd page of endpoints) and scroll down to the response section. Here we can edit the json Response if that response needed to be generated in some custom way. We can also enable templating via the checkbox, and make the status value return what was inputted as a querystring parameter for status using handlebar syntax. Remember to click "Apply changes" to save the modified simulation to the running service.

[
    {
      "id": 1,
      "category": {
        "id": 1,
        "name": "dogs"
      },
      "name": "Woofles",
      "photoUrls": [
        "image/woofles.jpg"
      ],
      "tags": [],
      "status": "{{ Request.QueryParam.status }}"
    },
    {
        "id": 2,
        "category": {
          "id": 2,
          "name": "cats"
        },
        "name": "Simba",
        "photoUrls": [
            "image/simba.jpg"
          ],
        "tags": [],
        "status": "{{ Request.QueryParam.status }}"
      }
  ]

Test this endpoint from the browser, cURL or Postman including the following path and querystring to your service URL "GET/v2/pet/findByStatus?status=pending", and the above json should be returned but with the handlebar template functions having been replaced with the word "pending".

Part 5. Test the POST /v2/user endpoint

Follow these steps:

Locate and click on the POST /v2/user endpoint to open it's properties.
This endpoint is for the creation of a new user by supplying a json object with the user details in the Request body.
From the Swagger file, the Request has been set to respond to exact matches of the Request body to a json object conforming to the schema and values specified in the Swagger document for a user. So in order for Hoverfly to recognise and respond to a POST to this endpoint, that exact json must be supplied, which might not be the behaviour you need when creating a simulation that needs to respond to variable data in the POST's Request body.
The current JSON Matcher looks for this exact JSON to be present:
```
{
    "id": 0,
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "password": "string",
    "phone": "string",
    "userStatus": 0
}
```
Where as it might make more sense to change the Matcher to a Glob matcher with a value of * for the body, in which case any body sent would be a positive match and a response returned.
Navigate to the simulation editor for the service, locate the Request matcher's Body, and change the it from an Exact match to a Glob match for *
Remember to click "Apply changes" at the top of the screen to save your changes to the running service.
You won't be able to test from a browser as we need to do a POST, so with Postman set up the endpoint to POST to https://petstore-youraccount.hoverfly.io/v2/user. You can put anything you like in the body.
Hit the endpoint and you should receive a 200 OK status response with no body.
Change the Response body to include something more meaningful, for example the json below, apply the changes, and test that it works no matter what you put into the Request body:
```
{
    "message": "success"
}
```

Part 6. Simulating Errors

Follow these steps:

We now have a POST that simulates successful user creations. But what if we wanted the API to occasionally return an error to ensure that the caller's error handling is working correctly. To do that we can introduce Behaviours into the running service.
Navigate to the Dashboard and locate the petstore service under Services.
Click the + sign to the right of the service and click it to bring up the Behaviour configuration screen.
Let's add a 405 error to occur 50% of the time.
Now when we test the POST endpoint from Postman, you will notice that the service sometimes returns a 200 OK, and the rest of the time a 405 Method Not Allowed.
There are a number of other behaviours that you can experiment with including latency and replacing text in the Response with something else.

Part 7. Remove the service and simulation

Follow these steps:

Unless you want to keep the service and simulation, they can be deleted.
To delete the service and it's copy of the simulation navigate to the Dashboard, open the ellipse to the right of the product service that you created, and select Delete.
To delete the master simulation, navigate to the Simulations page, locate the simulation you created, and click the corresponding x at the right of page.

Congratulations! You have completed this Tutorial, "Create a service and simulation by importing from a Swagger specification."

PreviousTutorial 1: Create a service and simulation manually NextTutorial 3: Create a service and simulation by capturing real API traffic

Last updated 8 months ago