APIs (Application Programming Interfaces) are becoming more and more popular nowadays as a lot of services use them to communicate with the outside world. As such, as they grow in usage, you can bet that there is a need for documentation, so that people can figure out what they can do with them.
After checking out a fantastic Learn API Doc course from Tom Johnson, I decided to dive into Swagger, one of the more popular “specifications” for API documentation. Fortunately, Tom also had a dedicated section to it that acts as a decent, albeit now outdated guide. As such, I decided to write this one.
Why do I need a specification?
You can document an API in any way you want. I’ve even described them using tables in Confluence due to restrictions at my work place. However, if you really want to make things easy for readers and deliver information in a good way, a specification, such as Swagger, is crucial.
There are several components to Swagger. First up, there’s the specification that relates to how the core content files are written so that they can be displayed by the Swagger UI. The latter is a framework that takes a file, written according to the specification in either YML or JSON and displays API endpoints, methods of interacting with them, mandatory and optional parameters, not to mention usage examples with requests and replies.
What’s more, it also enables users to implement their own API keys and make requests from the browser, instead of going to their own programs or tools.
Setting up the environment
Before we begin, it’s best to clear up a few things. Each instance of Swagger UI is its self-contained “webpage”. You edit a
.json file that gets processed by the framework and displayed inside the
- Download the framework by going to the Swagger UI GitHub project.
- Choose Clone or download > Download as ZIP.
- Save to a path on your PC and from the archive, get just the
- In the
distfolder, create a new
.yamlfile or download a template
.yamlfile. Feel free to use mine from this link.
index.html, go to the line specifying url: and enter the name of your
.yamlfile, so that it can be retrieved correctly by the framework.
- Open the
swagger.yamlfile in an editor of your choice. You can go with Notepad++, although I used Atom.
Editing the YML
The tricky part now begins, as you have to edit the YML file in order to add your information. If you have developed an API, you can use that as the source for your documentation. I used the REST Countries API.
Things may seem a bit complicated and YML isn’t exactly the most flexible markup language, largely due to the indenting that didn’t fit my settings in Atom, but you will soon get the hang of it. I also used for reference the more complex Pet Store example offered by Swagger in the web-based editor.
Things got a bit tricky when adding the response schema, as the initial example from Tom had no such thing and the official sample used references to generic examples. However, as you can see in my own file, I managed to master it.
The official Swagger documentation is also handy, although it seems a bit cluttered for my tastes (everyone’s a critic!).
Getting everything available online
As mentioned above, a Swagger UI instance is a website, so you need to host it somewhere to see it. For testing purposes, you can just open the
index.html file locally. You can also host the site using your local machine by employing XAMPP. I took the easy way and, since I already had the website for my portfolio powered by GitHub Pages, I added the dist folder in that repo and, voila, the Swagger UI example is live at this address.
My example is a basic one, with just three endpoints that use the GET method, but I plan on adding a few more things in the future.