HOW TO: Contributing to WireMock API Templates Library

In this guide, we will delve into the internals of the WireMock API Templates Library, and see how to contribute your own API mock template to the repository. As a demo, we will use the Hacker News Mock API definition created in the previous guide.

Prerequisites

• A GitHub account and basic Git/GitHub knowledge. Check out this guide with open source contributing basics if needed
• A WireMock Cloud account, free tier is fine
• An OpenAPI specification for the service that you want to mock

Step 0. Create a mock definition with WireMock Cloud

Unless you already have a ready Mock API project, follow this guide to create one for the service you want to add to the template library.

Step 1. Fork and clone the templates repository 

We maintain an open repository of API templates that can be used with WireMock, WireMock Cloud or other compatible services.  As common in open source, you will need to do the patches locally or from the GitHub web interface. If you're not experienced with Git SCM or with the GitHub open source contribution flow, the one to learn more, see the introductory documentation and examples here.

1. Login to GitHub and go to https://github.com/wiremock/api-template-library
2. Click the "Fork" button in the upper right corner. It will create and open a fork in your account
3. In your local fork, click the "Code" button and use one of the clone options, e.g. Git or GitHub CLI to create a local development branch
4. Create a local development branch, e.g. via “git checkout -b my-template”

The template repository is pretty big and it may take several minutes to clone the repository. Later you will be able to pull the changes incrementally and it will be much faster.

Step 2. Prepare a directory 

All information about templates is stored on a per-folder basis, and the template pages provide a quick way to find and improve the template.

1. Based on your service name, create an appropriate directory path, e.g. "api/Y/ycombinator.com/news_v0" for the Hacker News API in the sample
2. Download the OpenAPI file to the directory
3. If you have a logo for the service and a permission to use it, also download the logo in the PNG, JPEG or SVG format
4. Rename all files according to the template below. Later we will use the file names in the metadata files

Step 3. Download the Mock definition file

Now we will export the project API stubs from the Step 0 and add it to the repository as a “*-stubs.json” file in our repository folder.

1. Go to the WireMock Cloud web interface, and open your project
2. Click the “Export” button on the upper right panel
3. Click the “Export WireMock JSON” button

Step 4. Create metadata files for the template

We will need two files: “index.md” and ‘*-metadata.json“. The easiest way is to copy these files from one of the existing templates, and then update accordingly. We will use the template from the WireMock Admin API as a base (source).

1. Set up the “slug” field similar to the directory name - we recommend a unique combination of the service ID and version
2. Define name, description and provider of the template
3. Update “logo” and “stubs” to point to the previously created files. “logoMediaType” should be aligned with the format
4. Set the tags. You can find the list of available tag IDs and names on library.wiremock.org. In this example, we set the “social” tag and also “featured” since we will highlight it. In your templatesm, do not put the “featured” tag in your template without discussing with the maintainers in the pull request first

The second metadata file is index.md which is not a common Markdown file, but an empty file that holds the same metadata as above but in YAML format needed by the Templates website. Later we plan to remove the need for such duplication when submitting patches. For now, you can convert the file above and paste in the contents:

slug: "wiremock-org-admin"
title: "WireMock"
provider: "wiremock.org"
description: "WireMock Admin API"
logo: "wiremock.org-admin-logo.svg"
logoMediaType: "image/svg+xml"
tags:
- "developer_tools"
- "wiremock"
- "featured"
stubs: "wiremock.org-admin-stubs.json"
swagger: "wiremock.org-admin-swagger.json"

Step 5. Submit the pull request to WireMock 

Now all the necessary files are ready, and you can submit them to the GitHub repository as a pull request

1. Add all files to the local Git change tracking, e.g. via the "git add <file>" command
2. Commit the changes, then push them to your GitHub fork
3. Go to your local fork
4. Create a pull request to the main repository in the WireMock GitHub organization. 
5. Fill in the fields in the pull request template

‍

Your pull will be reviewed by the maintainers within a few days. If everything is fine it will be integrated and automatically published to the website. If it’s stuck due to whatever reason, ping us on WireMock Community Slack, #help-contributing channel.

Optional: Step 6: Submit the OpenAPI file to APIs Guru!

In our work we use APIs Guru - a public and machine readable repository of OpenAPI specifications. If you have a new service not yet published there, we recommend contributing your specification there.

The end!

Pull requests submitted in Step 5 will be reviewed by the maintainers within a few days. If everything is fine it will be integrated and automatically published to the website.

Start contributing

We invite you to contribute new API Mock templates to https://github.com/wiremock/api-template-library , and to enhance the existing ones. If you are looking for some ideas about what service mocks to create, checkout the good first issues here. We will be adding more tickets soon, and this repository also will be a part of Hacktoberfest!

Also join us on WireMock Community Slack, and use the #help-contributing channel to get any support when contributing to WireMock, including the templates library.