API documentation using Swagger

Intro

Wanted to create an API spec for brainstorming an API that we’re developing. Swagger is probably the most popular API design tool. I had used Apiary (https://apiary.io/) in the past (2013-14). It had features like defining the API spec using yaml and it getting rendered beautifully as API documentation. Nothing like a great API documentation that shows different methods, parameters, objects, input/output status codes and even a server/sandbox to try it out. It makes the life easier for consumers of the API. Currently a lot of companies use tools like Swagger, and the API documentation is quite good. The struggle to understand an API and get help to consume it is a thing of the past. API design is probably one of the most impactful aspects of software development since the right design goes a long way to lay the foundation of a solid system that works great for the service provider as well as clients.

Great API documentation examples

The model API documentation to follow are probably the following -

Plaid - https://plaid.com/docs/
Stripe - https://stripe.com/docs/api
Twitter - https://developer.twitter.com/en/docs/api-reference-index
Github - https://developer.github.com/v3/guides/getting-started/

Back to Swagger, here is a quick explanation of Swagger from their website -

What Is Swagger?

From https://swagger.io/docs/specification/2-0/what-is-swagger/

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API. This file is essentially a resource listing of your API which adheres to OpenAPI Specification.

The specification asks you to include information like:

What are all the operations that your API supports?
What are your API’s parameters and what does it return?
Does your API need some authorization?
And even fun things like terms, contact information and license to use the API.

Installing Swagger editor locally

There are two options to use the Swagger editor (https://swagger.io/tools/swagger-editor/). You can download the editor or use the cloud version, which is the ‘Swagger Hub’. Wanted to try the cloud version since there would be no setup needed for it. It asked for sign-up or creating the account using Github. Did that and then thought it may not be a good idea to use the web. Might be better to install it locally and run. So went back to the editor page and clicked on ‘download Swagger Editor’. That took me to the swagger github repository (https://github.com/swagger-api/swagger-editor). Was expecting a binary that I could use to install locally though.

Anyway, did a git clone and followed the instructions to set it up locally.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Install npm packages (if needed)
npm install

# Build the app
npm run build

# Build an image
docker build -t swagger-editor .

# Run the container
docker run -d -p 80:8080 swagger-editor

But this failed with the error

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

So installed docker. Used the local installable ‘Docker Desptop for Mac’(https://docs.docker.com/get-docker/). This had a getting-started example which was easy to follow and in a few steps was able to create a ‘getting-started’ container. The dashboard had a pretty UI to display the container. One could start/stop the container using the UI.

Using the swagger-editor docker image

Another option mentioned in the Swagger repo was to use a docker image that was already published in DockerHub. Should have used that instead of trying to build this locally.

docker pull swaggerapi/swagger-editor

docker run -d -p 80:8080 swaggerapi/swagger-editor

Navigating to http://localhost showed the beautiful Swagger UI with a pre-filled “Petstore API documentation”.

swagger-ui

Exciting! Now starts the actual API documentation.