Creating a Swagger Specs Document

What is Swagger?

Swagger is a documentation tool that will help you describe the structure of your API. Swagger does this by reading a JSON file which contains a detail description of your entire API. The specification asks you to include information like:

• What operations will your API support?
• What are your API's parameters and what does it return?
• Does your API need some authorization?
• Terms & conditions, contact information, license to use the API, etc.

There are two ways to create your Swagger spec for your API.

1. Generate your specs manually. Personally I like this approach better just because it helps you design your API before writing any code.
2. Have the specs generated automatically from annotations on your source codes. Check Swagger docs for a list of tools that let you generate Swagger from your code.

Creating Swagger specs

To create your Swagger specs, first go to swagger.io and sign in

So lets start by creating our first Swagger specs doc

For the specification we leave the OpenAPI 3.0.x value, and for the template we change it to OAuth 2.0 - Password and finally give our specs a name, we will call it New_API and hit on the Create API button.

Once the create specs finishes, we will get the following screen:

All of the docs in the swagger.io must be written in YAML format, which I think it is easier to work with.

Understanding Each Section

The info Section

Here we define some basic information about our API like its name, version and description

The paths Section

Here we will be defining all our routes and methods that our API will listen to, giving information such as what type of data we will be expecting to receive and return as all of the status codes we will be working with.

The components Section

Here we will be defining the schemas of the data that we are going to be receiving and returning

Create our route

For visual organization in our documentation, we first need to create a tags section where we will group each of the routes

You can add as many tags as necessary, just remember that with YAML files the indentation is important

Next inside the path section we start creating our routes, first we define the endpoint we are going to work with, and for each endpoint we need to define what methods will it allow (GET, POST, PUT, PATCH, DELETE)

When we write the description with a multiple line format we are allowed to use MarkDown language to format to format the text.

Congratulations!!! We've just created our first endpoint, now we need to model the data we will be receiving.

At the end you will have your documentation looking as the following:

We will continue with the Swagger specs definition in a later post