How to streamline the process of creating API documentation (not only) in GoodRequest

Today we bring you the first blog from a series of articles focused on projects from Hackathon 2021.

In this blog we would like to present the one of the first projects that were created during Hackathon and as you know from the name, it is used to create API documentation.

When creating the API, in addition to the implementation of the endpoints themselves, it is necessary to prepare its documentation. For historical reasons, this was written by hand for each endpoint using apidocjs. Of course, with each change that occurred during development, it was necessary to modify not only the source code but also the documentation. You may say that this is not terrible, just a few extra minutes of work. However, if we calculate the time needed to create documentation for the entire project, we can easily climb tens of hours spent transcribing.

In an ideal world, the result of this lengthy work should be correct and up-to-date documentation that other developers can follow. In the real one, however, there were often errors, typos or updates postponed indefinitely, and the documentation became out of date, and therefore unusable almost immediately.

‍

This situation has plagued us for a long time, but we have not been able to find a more suitable tool that would suit us. So, when we learned the theme of this year's Hackathon, it was very clear to us what project we would be working on.

Are you interested in how organize a Hackathon?

Our goals

We have decided not to write anything extra and to create a library that will be able to generate API documentation from the source code. It was important for us that the solution was universally applicable to anyone with a tech-stack similar to ours and that it did not require a big intervention in the source code.

And that is exactly what we managed to do 🙂

How express-joi-to-swagger works

Before Hackathon, we created a survey to see if our bold plans were feasible at all. On the backend, we use express.js to create the API in combination with Joi to validate inputs and outputs. We came across several libraries that provided partial solutions and decided to inspire them. One of them was the joi-to-swagger library, which allows you to generate swagger schemas from Joi objects. We obtained a list of endpoints registered in express routers together with a list of middleware functions thanks to express-list-endpoints. All we had to do was figure out a way to get the Joi schemas and a list of permissions needed to access each endpoint so that we didn't have to change the source code. We were able to find a solution to this problem as well, so at the end of the first day of the Hackathon we had a prototype that met all our criteria. We created a tool that went through a list of all endpoints and relevant middleware (routes) but also the definition of permissions and input parameters.

Our story does not end there

You will not be surprised that this solution has been a great success. The documentation that is generated automatically cannot be out of date or incorrect and also saves us time.

After the Hackathon, we managed to supplement the library with obtaining output schemes so that the documentation is really complete. We tested it on our own projects, tuned in the problems that arose and published it to the public. It is available on GitHube or npm. As stated in our README, we will be happy if you come up with ideas for improvement or reveal problems that we did not notice. We are open to cooperation with the community and every contribution to the project is welcome 🙂

We have several plans ourselves. At the time of writing, we have managed to release version 0.0.15, which allows searching in the documentation. Another goal of ours is to include automatically generated su in the documentation

Are you even tired of writing documentation by hand? Join us in our backend team!

‍