Nowadays, the development and use of REST APIs to communicate between servers and one or more applications is extremely common. After all, this API standard allows us to extract, insert, change and delete data on these servers. All these actions are performed by the REST API through the HTTP protocol ( Hypertext Transfer Protocol ) which, based on routes defined in the web service , establishes communication between the server and the applications. Allied to the great use of REST APIs, it is important to highlight the fact that one of the most used technologies, currently, for the development of this type of web service is Node.js. Through it, it is possible to build APIs using the JavaScript language in a very simple way, especially with the help of the Express.js module. But the truth is that the complexity and number of routes needed to serve one or more applications using a REST API are, in general, considerably high, which can make life a little difficult for those who are developing this application. On the other hand, we have a problem that could be even bigger. Developers who want to use the services provided by this API need to know well the actions that can be performed by it, as well as how to use them.

The importance of [ignored] documentation

All of these questions that were listed above can be easily answered through extensive project documentation, which, in turn, must be updated whenever new resources are made available or updated. This documentation is generally created using Swagger , a tool that allows us to create documentation using the JSON standard that already creates a visualization interface with all the data. But, for anyone who has worked with API development, you know that this documentation does not always exist. When it exists, it is hardly kept up to date, mainly considering that there are deadlines to be met in terms of deliveries. However, this "time gain" by not keeping the documentation up to date can become an excessive time expense in project maintenance, as well as a "headache" for those who want to use it. Given this scenario, is it possible, as the saying goes, to "unite the useful with the pleasant"? Yes, it's completely possible! In other words, it is possible to create our documentation and keep it always up to date; and that in a super simple way. Therefore, the purpose of this article is to teach you how to create and keep updated your REST API documentation, developed with Node.js, using Swagger, but in an automated way, through the swagger-autogen module .

Required modules and start of development

The swagger-autogen module will be responsible for generating the Swagger JSON file. Therefore, this module is the core of what we are proposing to develop here. However, for this JSON to be interpreted, we will also use the swagger-ui-express module . This second module is amazing, because it also allows us to integrate our documentation with Express.js, making it available in some specific route of our web service . Since we will be using Express.js, we will also use the express module . Finally, we will also add the body-parser module , so that we can correctly receive JSON files in our REST API. Ready! Now, let's create the index.js file , a swagger.js file , and two folders: routes and swagger . The first one will contain all the files of our API routes, just to make the project more organized (you could put all these routes in the index.js file too). Inside that folder, you can already create a file called main.js, which will contain the main routes (you can add other files for other types of routes as well, later). To the second folder we will direct the Swagger JSON file that will be created, so it will not be necessary to create files in it manually.

Conclusion

I'm sure with the swagger-autogen module , your experience with creating and updating the documentation of a REST API will be much better! There are still many other parameters you can add in these comments to make your documentation even more complete, but we'll leave that for another time. If you want to learn more about Node.js, creating REST APIs, and many other web development topics, we have an amazing Pi Web Full Stack course . In this course, you will become a complete and market-ready developer, mastering both front-end and back-end technologies. So don't waste time! Click on this link and learn more about this course. See you in our next post! A big hug, and until then...