Introduction

1. What is swagger-docs?
2. What is swagger-docs for?
3. What problems does swagger-docs solve?
4. How does swagger-docs works internally?

What is swagger-docs?

In web apps, it is necessary to keep record and maintain API docs as it becomes easy for other developers and general public to view and test out APIs fast. But this cost developers and organisation their time and energy to create and maintain those APIs and as the web apps evolve and grow in size it is nightmare for any developer to precisely record every information of the APIs.

Well don't worry this is where Swagger-Docs will help you. This library aims to reduce efforts and time to document web APIs.

What is swagger-docs for?

Swagger-Docs is designed to do the following:

• Fast API documentation
• Changes in APIs reflect immediately.
• Don't repeat yourself by writing code for route handler as well as writing api documentation.
• Customise API docs UI as you want.

What problems does swagger-docs solve?

Swagger-Docs is mainly useful for documenting apis built using plain node.js web apps, without any node.js framework. The problems that swagger-docs solves are:

1. Removing need to write comments, including jsdoc comments to document apis ✅
2. Removing need to update code comments for any change in apis ✅
3. Fast documenting APIs as you create and modify it ✅
4. Removing need to surf stack overflow for finding how and why of documenting APIs in Swagger ✅
5. Added Typescript support for ease in using and understanding ✅

How does swagger-docs works internally?

The internal structure is working based on Typescript decorators and Reflect Metadata APIs. The reflect metadata APIs helps to store metadata information about the object and when the app starts running with proper configuration, this library does following:

1. Gather the reflect metadata around the objects
2. Process it, perform validation and converts it in format compatible with Swagger UI config
3. The processed reflect metadata helps to define routes in web app, so you can call the API.
4. Then the processed metadata is set into Swagger UI config.

Where to go next?

Next up is Getting Started and get familiar with the library