Documenting APIs using Swagger

Sep 4, 2019 · 3 min read


Swagger provides a set of tools that allow developers to document APIs. API documentation is important as it allows clients/stakeholders to be able visualize the API. Its also facilitates the ease of collaboration when working across teams, the expectations from the API are made tangible that ensures everyone understands what is expected from them. In addition its important because for future improvements or in the event you want to add more functionality, if the API you are working on is well documented you have a solid reference point.

How to get started

To document my API, for the Andela Developer’s Challenge I used free option of a tool called SwaggerHub from Swagger. To get started you need to go to sign up on SwaggerHub. After successfully creating an account, you are able immediately to start documenting your APIs. But note on the free option you can only document up to five APIs.

Creating an API

To start creating an API, on SwaggerHub you simple click on the `Create API` button. SwaggerHub then responds with a modal which offers you option to generate a template which you can use create your API. I used an OPENAPI Version 2.0 and the Petstore Template. When using swagger 2.0 you have the option to use json or yaml. I choose to document my API I using yaml.

What is yaml ?

“YAML is a human friendly data serialization
standard for all programming languages.” —

Technically YAML is a super set of JSON. This means that, in theory at least, a YAML parser can understand JSON, but the opposite is not true. And its important to mention that YAML uses white space indentation, so when documenting in YAML you need to be mindful of indention. As its been stated YAML is used for data serialization.

Documenting an API

For the most part I used Swagger official documentation. I will create a typical user sign up endpoint to illustrate typical work flow:

Setting up meta data

Defining your request

The endpoint ‘auth/signup’ is an object with several properties which include post, produces, parameters, and response. So all those properties are defined in the format shown.

Defining your response

To define your response you state the http status code, which in this case is a 200. The schema keyword describes the format of the response.


Swagger comes with a lot of tools integrated to it which not only help developers document APIs fast but some like Swagger Inspector allows one to easily validate and inspect APIs.

More From Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade