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 .
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.
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...
Dont miss out on the news!
Join the MAKE NOW academy to receive exclusive content every week!