Sean Kennedy
Sean Kennedy
February 17, 2016

3 Best Practices for API Development with Swagger (Open API)

My first exposure to (now Open API) was almost 2 years ago. I was looking for a tool to document an existing RESTful API. Concerned that if the documentation was “too far away” from the source it would fall out of sync with the API, I ultimately chose something else that let me decorate the functions directly.

Clearly that solution was unsatisfactory, as less than a year later, with broader participation from our internal developer community, we’d be building Swagger support right into what would become our Node.js BlueOak Server.

Executable API

My desire to have the documentation close to the implementation came from experience writing software libraries, but we found we could do something better with Swagger for RESTful APIs: the spec could be made executable. When you develop an API using Swagger and BlueOak Server, you don’t just use it to generate docs to share with your users: BlueOak server loads your Swagger API, connects the paths it defines to your implementation code, exposes that API to the network, and validates that every request is well-formed per that API.

Since building this support into BlueOak we’ve benefited from it on our projects, and have uncovered some best practices for writing Swagger specs.

Best Practices for Building Swagger Specs

1. Use a Local Editor

The web editor was a really helpful way to get started with Swagger. As we got more experience with our workflow, however, it became clear that local editing was the way to go.

Here are my top reasons for writing Swagger spec using your local editor:

  1. Iterative workflow. Unless you’ve got a spec from somewhere else and have to use it as-is, you’ll be iterating on the spec as you build your implementation. This is a natural pattern of iterative and agile development, and becomes exceedingly difficult if you’re always having to export your file to a web editor, make changes, then download and import it again.
  2. Delivering documentation with Swagger UI. For better, or worse, how Swagger specs get processed and rendered is different between the Swagger editor and the Swagger UI doc tool. If you’re planning to provide documentation for your API using Swagger UI, then you’ll save time in the long run by referencing the output pane of the Swagger editor only to find it doesn’t render the same in Swagger UI.
  3. Breaking your spec into multiple files using external JSON references. As I’ll explain below, this is something you definitely want to do.

2. Choose YAML

When we first started with Swagger, we were using JSON to define the specs because it was familiar to us. While the terseness of a YAML-based spec definition was attractive to many of us, what finally convinced everyone was how much better we could write docs using YAML.

I think comparing this YAML, with the equivalent JSON, speaks for itself.



3. Use External References

Without the use of external JSON references, you have two choices for your specs:

  1. Put everything in a single file. This is exactly what you can see from the Swagger editor examples. Unfortunately, this leads to massive files. The Instagram example is over 1000 lines and the Twitter example is over 3000 lines. Of YAML. We had one API weigh in at nearly 7000 lines of JSON.
  2. Break your API into several spec documents. This, unfortunately, produces a lot of duplicate code: you can’t share your model definitions, responses, parameters, or even security definitions, between documents.

We did projects trying out both approaches, but ultimately a third way won: using external JSON references.

Here is an example of using external references from BlueOak Server’s swagger example (based on the Uber example from Swagger editor):

You’ll find the “$ref” syntax in the swagger samples from the editor, but instead of referencing an anchor in the current file, it references an external file.

Swagger Spec Development with BlueOak Server

If you want to see what it’s like building a Swagger spec following these best practices, take a look at the Getting Started with Swagger section on the BlueOak Server wiki. As with all of BlueOak, our goal is to make our best practices executable and repeatable.

See my other posts on BlueOak if you’re interested in learning more.


Filed under:

If you like this, you'll like these:

More Blog Posts


With the strength of Globant behind us, we’re powering up our focus on transformative digital solutions.

On July 30, 2018, find all new content at

See More