API Documentation 2.0 with Swagger and Stoplight at Namely

A quick Google search on how to best document your API will return a myriad of tools ranging from framework specification formats to software that will generate documentation with a slick and aesthetic UI. This article will break down our experience and experimentation with these tools, and what ultimately led to our optimal final product: API Documentation 2.0

Part I: The Philosophy

Your API is a living and breathing document — yet the API documentation itself is a contractual agreement between two consenting parties. It is a company’s moral obligation to uphold their end of the agreement by providing clear and accurate documentation.

Our team at Namely decided to adopt a philosophy moving forward where the API design drives the code . This can be broken down into two commandments:

1. All new APIs must be designed first.
2. The API design will change, and the framework must make it possible to adapt quickly without letting the code, design, and documentation fall out of sync.

In order to make good on this philosophy, we decided that we needed a specification framework that would act as the source of truth for our API that automatically generates documentation.

Part II: The Specification Framework

The leading players in the API specification framework field are: Swagger, RAML, and API Blueprint. Swagger stood out to us from the beginning because it is the most heavily adopted, with a large community of users and supporters, and has the greatest support for multiple languages.

Swagger allowed us to establish a set of rules for describing our REST API with a document that details all the URI paths for an API, query parameters, and the request and response bodies. The format is both machine and human readable. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.

An extra benefit of having our entire API documented in Swagger format in GitHub is that it incentivizes transparency and collaboration for proposed amendments to the API. This leads to improved architectural design as well as company-wide notifications when a piece of core functionality changes.

An example from the YAML Swagger file from the Namely API:

Part III: The API Documentation Generators

The next step was to figure out how to host the documentation and which developer portals play nicely with Swagger. The API documentation generators we sampled were: ReadMe, Gelato, and Stoplight.

ReadMe
Our API documentation was originally hosted on ReadMe and input manually from a template and text fields before we adopted Swagger. As you can imagine, this process was time intensive and caused our API documentation to regularly go out of date. ReadMe is currently in beta mode for uploading Swagger files and automating this process, and unfortunately, wasn’t at the level of reliability and functionality we felt comfortable moving forward with. Additionally, ReadMe did not offer support for a sandbox to make test API calls.

The original API documentation hosted with Readme.io

Gelato
Gelato smoothly consumed Swagger files (even with error catching!) and a host of other improved features such as a markdown editor and interactive API explorer where you could utilize an interactive sandbox to make test API calls.

However, there were two major holdups with Gelato:

1. The Lack of Support for Variables
   Namely uses a subdomain for each client in the following format:

<<subdomain>>.namely.com

The subdomain is meant to be replaced with the company’s name for their specific data, such as Hooli or Pied Piper. Without the functionality for variables, this would make testing the API endpoint in the sandbox ineffective.

2. The Counterintuitive UI and Heavy White Space
The documentation auto-populated the first item with the name of the path and its corresponding model definition to create the Endpoint Overview. This falsely led the user to believe that the /countries index would return only the Countries definition model, when it would actually return an object with 3 model definitions such as: countries, links, and meta.

Namely’s API documentation hosted by Gelato

Stoplight
The classic idiom of “third time’s the charm” rang true once we tried out Stoplight. Stoplight not only offered all of the previously mentioned features, but also supported variables. The UI was the best we had seen among all of the contenders thus far when it came to the user experience, design and customization. Additionally, Stoplight processed the Swagger file instantly while Gelato took about 4–5 minutes for processing which slowed down the development process.

Stoplight’s newest product is called “Scenarios” and allows you to test, automate, and debug web APIs + AWS Lambda. We were able to utilize this feature to our advantage by automating the import process between our Swagger file on Github and Spotlight — so the code and documentation are never out of sync since the documentation is always regenerated. 🎉

The new and improved Namely API Documentation hosted by Stoplight

Conclusion

Swagger and Stoplight definitely stood out from the pack and proved to be a winning duo for creating beautiful API documentation with ease. Check out our new API documentation at developers.namely.com and let us know what you think!

Katie Reed is a software developer at Namely. Namely is an all-in-one platform for HR, Benefits, and Payroll. We’re hiring for Engineering, Product, and Design roles — check out all of our jobs here.

Thanks to Chris Lott at Spotlight for his responsiveness to my queries.