Swagger is Awesome for Quickly Creating API Documentation

This past week at LeadsPedia we decided that our API had reached the point in it's growth where we should stop updating a Word doc with new endpoints and actually put the documentation online. What's hitherto kept us from doing so is that it just hasn't been worth the development time with all the new features we're rolling out every week. We still didn't have a lot of time to spend on it though, so we set out to find a quick solution.

There are a number of different proprietary and non-proprietary solutions out there. All seemed to have their pluses and minuses, so it was somewhat hard to choose. Eventually I decided to have a go with Swagger because that's what Habit RPG's API is written with and I've done some development work with them. I figured worse case scenario was wasting a few hours going in a direction we wouldn't end up using. I was not disappointed. Swagger was fairly easy to use and took less time than I had imagined.

An Example: LeadsPedia's API

There are basic two parts to a Swagger API documentation: 1) a JSON holding the data about your API, and 2) the UI interface that parses the JSON and and makes test API calls via AJAX. There is a bit of a learning curve to understanding the format of the JSON, but the Swagger Editor provides examples and a test interface to get you up to speed fairly quickly.

Let's take a high level look at the JSON:

The paths and definitions are where the real meat of your API documentation is stored, so I will cover those in a bit. First thing to note is that this JSON is readable by anyone who has access to your documentation, so it contains no API credentials. The UI provides your users fields to enter their own api credentials and then uses them in the example AJAX calls to your API. This is a great feature because they're immediately interacting with their own data and you don't have to worry about setting up any test data to work with.

The first property of the JSON is swagger, which merely specifies the version you are using. Next up is the info property, wherein you specify the information to appear at the top of your documentation: a short description, the version, what the terms of service are, contact information and the like. Next you set up the host and basePath. These are important because they will form the start of the url of your endpoint. The tags property is useful if you have a jillion endpoints and you want your users to be able to limit what they are seeing to a specific tag or tags. We didn't implement this feature because we don't have a jillion LeadsPedia endpoints. Yet.

As you can see, so far everything has been fairly high level. Now let's dive into a path:

As you can see, there is a lot happening here even though we are not using all the options available in Swagger by far. In your documentation, the name of the property, in this case /advertisers/create, will be appended to the host and basePath to form the URL in the example created when somebody clicks "Try it out!". The properties of the path are HTML request methods: GET, POST, PUT or DELETE. For ease of use, we have designed the LeadsPedia API to work whether you're using a GET or POST method to send in your data. Thus our decision to specify post here was somewhat arbitrary, but I thought it would be less confusing than having each endpoint in there twice.

The first property of the post method, tags, is included so that later when we have a jillion endpoints our users can limit them to advertiser endpoints by clicking on a tag. Again, we left this feature out of our current UI version, but it's easy to add back in. Next up is the summary property. This is a short string which appears on the line with your endpoint:

When the user clicks on the endpoint to expand the details, the first thing they see is the description. This is a longer form explanation of what this endpoint does and how to use it. (I abbreviated this one for the example.) operationID is the subpath of your endpoint and the produces property is an array of different output types this endpoint produces. In our case, we always output a JSON.

The parameters property is where Swagger really shines. If a parameter is required by your API and you specify that here, then the UI won't let the user try it without specifying a value of the correct type of input for that parameter! All of these example parameters are strings, but integer and other types are also available. Also notice that the last parameter named "portalAccess" is an enum. This leads Swagger to create a dropdown in the UI.

The last property is responses. Here you can specify what various HTTP responses, e.g. 200, 404, 301, etc, mean. Again, for ease of use we designed LeadsPedia's API to always respond with a 200 and provide verbose error messaging instead of requiring our users to interpret the response type.

Finally, let's take a look at a definition:

This is what the data structure of our API responses look like. Definitions like this can be used to specify what a response looks like, however, Swagger does not allow for different substructures (our results and errors differ for each endpoint) to be embedded under this superstructure. Ergo in the end I decided to leave out these specs and let the example responses from the AJAX calls under "Try it out!" speak for themselves. This is probably my only complaint about Swagger right now, but hopefully they will improve on that in future versions.

Conclusion

All told I was able to finish the documentation of the LeadsPedia API complete with functioning examples and a bit of whitelabeling in a single afternoon. I probably spent nearly as much time writing about it in this blog. While there are a few minor shortcomings (i.e., in the data definitions), there are plenty of features to document any web based API quickly. I was so impressed with the ease and speed of implemention that I felt the need to share! Next time you have an API to document, you should definitely consider using Swagger.