February 17, 2016
My first exposure to Swagger.io (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.
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:
- 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.
- 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.
- 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:
- 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.
- 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.
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.