Design, document, and mock your APIs with Swagger

What is Swagger and OpenAPI?

Swagger is tool for designing, building, documenting, and mocking APIs. It uses the OpenAPI specification (yaml or json files) to describe requests, responses, and any other details about your RESTful APIs.

Using this spec you can then generate documentation and even create a mock server.

Note: this story is meant to address creating an API from scratch. If you want to create documentation from existing APIs, there are other solutions, stories, and tips for this.

Photo by Yianni Nicolaides on Unsplash

Setting up Visual Studio Code

Microsoft’s free Visual Studio Code provides a great set of tools to create, edit, and verify your OpenAPI spec files. After installing VSCode you should install these Extensions (unsurprisingly using the Extensions button on the left):

• YAML (link)
• Swagger Viewer (link)
• OpenAPI Swagger Editor (link)
• Swagger Snippets (link, optional)

Once you create a yaml (or json) file and add the basic OpenAPI structure, the API icon will appear on the left and you’ll have the option to preview the documentation using Shift+Option+P.

The sample Petstore API yaml with Swagger Editor on the left, with Swagger Viewer on the right

Create and edit your OpenAPI spec files

First off, create a *.yaml file. (I will be demonstrating examples in YAML, but JSON is also supported if you are more comfortable with that standard.)

Although you can browse through the specs, it’s probably best to start off with a simple example — this describes a fictional API for the ubiquitous “Todo app”:

I won’t go into too much detail about the specs, as there are many tutorials out there, but as you can hopefully read from the yaml, OpenAPI allows you to specify in detail the requests, endpoints, responses, and data-types of your API. You can also define reusable components that you can then reference several times in your specs (to limit repeating yourself).

A somewhat more complex sample is the Petstore API yaml — this illustrates more advanced features of the OpenAPI spec. But probably the best is to start playing around with it (with a generated preview, see below) and just look up stuff in the specs when you run into trouble.

Generate documentation

Undoubtedly your yaml files are beautiful, but ultimately the goal (or rather one of the goals) is to generate documentation that the less-geeky members of your team can read. In addition, you can live-preview your yaml changes which can aid you a lot while writing the specs.

Though there are a number of different ways to generate documentation, I prefer using a command line tool for generating a totally dependency-free (and nice looking) HTML via redoc-cli.

First, install redoc-cli with npm (here’s how to install npm in case you don’t have it yet):

Now you can generate a full HTML documentation from your OpenAPI specs. You can also start a server that watches for yaml file changes (super useful while you create the specs). Here’s how:

You can also automatically generate documentation using your CI — if you use Gitlab, then you can set it up easily so that docs are generated and published to Gitlab Pages using Gitlab’s shared runners.

Use the --watch flag while running the server to watch for changes in your yaml. You’ll still have to reload, but it will update each time you change something.

Run a mock API server

As a project’s development gets underway, it often happens that the server API is not yet fully available when you must already rely on it for your app or frontend web development. Of course you can also mock the API data within your app temporarily, but even better is if you had access to a full-fledged mock API server that works identical to documented expectations.

While a service like SwaggerHub can provide this for your entire team, a free and fast alternative is prism. Just install it with npm (again, here’s how to install npm in case you don’t have it yet):

Then run it on localhost. Now you can access your API, as documented in your OpenAPI spec on localhost via the port you defined. Go ahead, test it via curl:

Prism has a few different config options, some as command line switches, some as special query strings. Check out the documentation for more detailed info.

Use generated data for API responses

So far we’ve created a mock API that will return static responses based on the examples (or data types) set up in our yaml spec. But this is only partly useful — much better is if we could get correctly formatted data generated randomly into each field.

Fortunately this is possible using x-faker tags in our spec. Based on faker.js, you can specify a wide variety of data types that will then be used to generate realistic, fake data for your mock server response. For example:

The above x-faker tags will tell prism to generate a valid, realistic, random first name and an existing photo url for the relevant field. You must then also run prism in dynamic mode using -d or request the endpoint with the __dynamic=true query parameter:

What’s next

There are many other features of Swagger that are outside of the scope of this short intro.

• You can use Swagger CodeGen to generate code stubs for your server and client side.
• On the other hand if you have existing code you wish to document you can follow solutions, stories, and tips for generating OpenAPI specs from existing APIs.
• If you use Gitlab, then your docs can be generated and published to Gitlab Pages using Gitlab’s shared runners.