How to take your APIs to another level with Swagger

Imagine a situation where the backend and frontend don’t communicate assertively. Imagine a situation where QA cannot test an API. Imagine a situation where the CTO doesn't know how to authenticate to the API, or, even worse, has to ask over and over again, again and again, which endpoints make it up.

In most cases, this is the sad reality, wasted time, miscommunication, attrition on both sides, and lots and lots of frustration.

When working on the backend in most cases we ignore the documentation of the APIs we build. That’s why, many times we have problems, or the results are not as expected because the developer who is making the user interface of the application does not have enough tools to understand the operation of each endpoint.

This is when the only solution is to spend hours and hours reviewing the code and understanding what each component does, and to be honest, that only leaves us with more delays and obstacles to achieving our goals.

Under this premise, Swagger emerges as a set of open-source software tools to design, create, document, and consume RESTful web services. The main objectives of this tool are:

• Minimize the amount of work required to connect decoupled services.
• Reduce the amount of time required to accurately document a service.

Swagger’s open-source tools can be used to interact directly with the API through the Swagger user interface. This project allows direct connection to the APIs through an interactive HTML-based user interface. Queries can be made directly from the user interface and options are explored by the user of the interface.

Next, we will see the implementation of Swagger inside our applications with Node JS.

The first thing to do is to install the following packages in our project:

npm i swagger-jsdoc swagger-ui-express

After that, we go to our index.js file and import these two libraries.

const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

Once we have the two imported libraries we will continue creating our Swagger configuration For this, we will create an object and we will pass it the configuration values that we want.

const swaggerSpec = swaggerJsDoc({
  swaggerDefinition: {
    info: {
      title: 'Manual Verification API',
      version: '1.0.0',
      description: 'Service to make manual credential verifications',
    },
    securityDefinitions: {
      basicAuth: {
         type: 'basic',
      },
    },
   },
   security: { basicAuth: [] },
   apis: ['./src/home/*.js'],
});

To finish with our index.js file, we will create a new path to access this resource and we will pass it the configuration we created earlier.

It is usually common to find that the path is named: /docs

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Finally, to finish with our implementation we must go to where we have our endpoint routes to establish a description, labels, and the format of the body that we must send in the request in order to facilitate the understanding of the task that each endpoint fulfills.

/**
 * @swagger
 * tags:
 *   name: Queue
 *   description: Service to make manual credential verifications
 */

/**
 * @swagger
 * /queue:
 *  get:
 *      summary: Get a manual verification
 *      tags: [Queue]
 *
 *      responses:
 *              '200':
 *                 description: A successful response
 *                 content:
 *                   application/json:
 *                     schema:
 *                       type: object
 *                       properties:
 *                         offset:
 *                           type: integer
 *                           example: 1
 *                         limit:
 *                           type: integer
 *                           example: 10 
 *                         size:
 *                           type: integer
 *                           example: 10 
 *                         users:
 *                           type: array
 *                           items:
 *                             type: object
 *                             properties:
 *                               id:
 *                                 type: string
 *                                 example: 65sa8d88d8g82kkk4fae
 *                               firstName:
 *                                 type: string
 *                                 example: sebastian
 *                               middleName:
 *                                 type: string
 *                                 example: ''
 *                               lastName:
 *                                 type: string
 *                                 example: Restrepo
 */

After we have done this, when we run our API and go to the /docs path we should be able to visualize our endpoint like this:

In addition, if we generate the documentation of all the endpoints of the application, we should be able to visualize a suite where all the API paths can be tested as follows:

You will be able to make requests from this interface in a simple and centralized way, so you will know what each endpoint does and in what format you should make the requests.

In conclusion, its advantages predominate in such a way that Swagger can be defined as the standard application par excellence for describing interfaces in RESTful APIs. Swagger is widely distributed and therefore compatible with many tools. It is used by technology giants such as Microsoft, IBM, and Google, so it has unconditional support.

If you want to learn more about this powerful tool, you can visit the official Swagger documentation at the following link: https://swagger.io/docs/specification/basic-structure/. I hope this post has helped you “take your Node application to the next level”. If so, I hope you will share this article with people who might be interested in this topic. 👏🏼