API Documentation With Swagger

Raj Kumar Shrestha
Apr 19, 2017 · 3 min read

Documentation is a set of documents provided on paper, or online, or on digital or analog media, for example, quick-reference guides. As a developer, it is very important to have reliable documentation about your work. It helps to jump into any development, maintenance and knowledge transfer of application. Most importantly, it is very helpful for other developers to understand programming code and application.

Application Programming Interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact. Most of the applications today are the web application and powered by API. Therefore, it is very important that API needs to be well documented to be understood and consumed by another developer.

There are multiple tools to document API, here I am going to start with Open API Initiative-Swagger. Swagger is simple and easier to write and is easy to consume from developer to developer. I am not going to talk about all the features, pros and cons of swagger.

Now, let’s start API documentation with swagger in YAML. You can write your document in your favorite text editor or you can use swagger-editor.

If you are using text editor then create a file user.yml.

Firstly, we add generic information about our api.

Then we will add details about each API path which falls under paths: tag.

Here, I am creating create user API along with its request parameters and response.

Definitions are path templating and referenced by $ref tag. CreateUserRequest and UserResponse are defined under definitions section and their paths are referenced to request parameters and responses.

In definitions, I have also made templates of users element which helps us to reduce repetitive work and update easily.

In the final document, we will put all together. You can also view this on gist. We have created a create user API. Similarly, we can build other APIs. In the beginning, it feels a little boring and time waste, but, after playing with the swagger documentation you will enjoy developing APIs.

In the next part, I will describe each part of the tags and UI for rendering swagger document. Stay Tuned.

Raj Kumar Shrestha

Written by

Software engineer @theCloudFactory

Shabda शब्द (words)