Creating Mock API templates from OpenAPI specifications

In this blog post, we discuss the process of creating new Mock API templates from the OpenAPI specifications. We will go through creating a new template for Hacker News and testing with it

In May we released a WireMock API Templates Library -  a public catalog of mock API templates for popular services and products. This service allows you to find the API that you need and get a running mock server in seconds, on both WireMock or WireMock Cloud. This catalog is open source and open for contributions, and we thank all the community members  who have participated and shared their feedback.

When creating a Mock API template, there are many ways which represent one of a combination of the following approaches:

1. Take an existing specification, for example in a Swagger, OpenAPI or a Postman collection format, and build a Mock API definition on the top of it
2. Use WireMock or WireMock Cloud’s Proxy and Record features to capture the communications with a server and have draft mock definitions (docs - WireMock, WireMock Cloud)
3. Create a mock definition from scratch by editing mock API stubs in your favorite IDE or in WireMock cloud

This walkthrough

In this walkthrough we will focus on creating a Mock API definition from an OpenAPI specification. We will use WireMock Cloud and its OpenAPI import feature that saves a lot of time and that was used to create the first edition of the API Templates library.

We will do the following:

1. Import an OpenAPI specification in WireMock Cloud. We will use Hacker News which you might use from time to time. If so, you can follow the WireMock account there and join us in the conversations :)
2. Enhance the specification to address OpenAPI limitations
3. Test a few requests in the mocked API
4. Share the newly created specification with the team and with the community

Prerequisites

• WireMock Cloud account. You can use a free account that takes just a few clicks to set up
• A ready to go OpenAPI specification for the service you want to mock. For the Hacker News example in this guide, you can download it from this commit we’ve contributed to the open source HackerNews/API project 

Creating a new Mock API

1. Log in to your WireMock Cloud Account: https://app.wiremock.cloud/ 
2. Click the “Create new mock API” button
3. Choose the “Blank - An empty API without stubs” template and click “Use this template”

4. In the new window, use “Hacker News Mock API” name
5. Keep the “custom hostname” field empty, a random ID will be assigned on the next step
6. Click “Save”

After these steps, you will get an empty project with the OpenAPI capabilities enabled.

Importing the OpenAPI specification

Now, we will import the OpenAPI specification. To do so. Click the “Import” button on the project page:

In the open Window, paste in your OpenAPI/Swagger specification For this walkthrough, you can copy the specification YAML from here. JSON specifications can be imported in a similar way.

After that, you will get a ready-to-fly mock API project which is exposed to a randomly generated domain name on *.wiremockapi.cloud. You also have the option of assigning a friendly domain name via the Settings page.

There you can see that multiple stubs (request/response pairs) representing several API endpoints  were generated from the OpenAPI definition, including getting Hacker News data items of different types, getting user profiles and the list of recent updates. Some endpoints serve both 200 and 404 error codes as defined by the specification. This date is intelligently extracted by WireMock Cloud from the OpenAPI definitions, examples and other metadata supplied as a part of the specification. 

Testing the API

Now you can connect to the mock API using its assigned domain name under wiremockapi.cloud. For each API stub you can use the “Test Requester” tool on the right side panel. For example, let’s use the “Get User Info - common-user” stub that returns the user profile. Select the stub in the list, click on the “Test Requester” pane to expand it, and then click “Send” to send the request to the stub.

You can also use direct URLs for testing the endpoints, similar to WireMock standalone instances.  

And yes, you still get all the WireMock troubleshooting capabilities when a stub is not matched! 

Enhancing the imported Mock API

As you may have noticed in the screenshots above, the imported Mock API is not ideal. Their current OpenAPI specification (version 3.1) does not support many features, e.g. the example requests do not include the request path, and hence WireMock Cloud has to guess the parameter values which is not easy for array objects like Post ID or string User IDs in Hacker News. It does not always work, and we might need to apply edits  

NOTE: The upcoming OpenAPI v4 (aka Moonwalk) Proposal plans to address many of these limitations. Among other goals, it aims to “Support APIs that have different responses based on query parameters, headers and request bodies” and “Improve reusability of request and response patterns”. And yes, WireMock has joined the OpenAPI Initiative behind this project!

So, let’s correct some endpoints in the request editor:

• For “Get User Info - common-user” change the user ID in the “equal to” field to “wiremock”, as returned in the sample response (see the screenshot below)
• For “Get Hacker News Item” requests you can set proper “equal to” values so that the request ID equals the response ID extracted from OpenAPI

Save the template for internal use

Once we have edited and tested the template, we can save it for future reuse ib your projects and or for sharing with the team. You can save the current project as a new template from the web interface:

Now, add information about the template and its name, then click “Save”

After saving, you can see the template in your private “Mock API Templates” view and reuse them for future Mock API projects. 

Optional: Share your template to open source!

We invite everyone to participate, submit new API templates and update the existing ones. To do so, follow the guidelines contributor guideline. In a week or so, we plan to publish a walkthrough of contributing your first template. Thanks for your participation!

In the meantime if you have an API template you’d like to contribute, please hit us up on the community Slack and we’ll help you through the process. For any feedback and suggestions, please use the GitHub issues in this repository. The website is powered by Hugo and open for contributions too!

More info

• OpenAPI specification and related developer tools: https://www.openapis.org/ 
• Importing Swagger and OpenAPI in WireMock Cloud: https://docs.wiremock.io/swagger/ 

WireMock APi Templates Library: https://library.wiremock.org/