API with NestJS #52. Generating documentation with Compodoc and JSDoc

JavaScript NestJS Node.js

This entry is part 52 of 177 in the API with NestJS

The reality of software projects is that people sometimes come and go. Therefore, the bigger our application is, the higher value we put on the ability to more easily introduce new teammates into the codebase. One of the ways to improve this process is to create documentation. This way, we can accumulate knowledge even if the people that wrote the code are no longer around and can’t explain their thought process in person.

The main issue is that writing and maintaining documentation takes valuable time. Since we could spend it on writing the actual code, it is sometimes difficult to justify it to the business side of our project. After all, time is money. Writing documentation can save us time in the long run, though. Fortunately, some tools can make writing documentation more manageable and less time-consuming.

An interesting fact about NestJS is that it shares a considerable chunk of the approach to the code structure with Angular. Because of that, a tool called Compodoc made with Angular in mind works with NestJS applications too.

Introducing Compodoc

Compodoc aims to generate the documentation for our project. It is open-source and can work offline. While it automatically creates the NestJS documentation, there are many ways to expand and customize it.

To start working with Compodoc, we first need to install it.

A fitting way to run it is to add it to the scripts in our :

package.json

Thanks to adding the , Compodoc generates the HTML files with our NestJS documentation and serves it at http://localhost:8080.

There are other flags that you might find useful. Type for a full list. For example, we can use to choose one of the available themes.

The cool thing that we see right away in the project overview is a visual representation of our whole architecture with our modules and services. If our project is big, it can help get a better grasp of the code structure and how various modules work with each other.

Documenting individual files

An interesting thing about Compodoc is that it analyzes not only modules and their dependencies but also individual files.

Fortunately, it can interpret our TypeScript code along with the information about the types. So, for example, we can click on above. This way, we can get more details about the argument of the method.

Providing additional information with JSDoc

While Compodoc can analyze our TypeScript code, we can help it by using the JSDoc markup language. It is a well-known way of writing comments in our code that various tools and IDEs can understand and support.

Compodoc supports the following tags from JSDoc:

@returns

With the tag, we can provide the return type of a method and describe it. However, since we use TypeScript, we can use it to define the return type instead.

@param

By using the tag, we provide the type of the argument and additional description. Again, we can use TypeScript to define the type of the argument.

@ignore

With the tag, we can indicate that some parts of our code should not be presented in the documentation. A good example can be the method:

We can use the not only with methods, but also with whole classes.

@deprecated

With the above tag, we can mark a method or a class as deprecated.

@link

We can use to provide an anchor to other parts of our documentation or an external URL.

@example

With the above tag, we can provide a code example that will be displayed in the documentation.

Documentation coverage

If you want to enforce the documentation to be written, you might find the documentation coverage to be valuable. With it, we can verify how much of our code is documented.

Compodoc doesn’t take private functions into account when calculating the coverage.

Documenting a file using markdown

Sometimes we might feel that documenting by placing the comments next to the code is not enough to paint a complete picture of our code. Thankfully, Compodoc supports creating documentations through markdown files. We need to place a markdown file next to the file we want to document and use the extension.

categories.service.md

Compodoc adds a new tab that we can click on to view our markdown when we do that.

Summary

In this article, we’ve gone through the idea of generating NestJS documentation with Compodoc. We’ve also learned how to customize it with JSDoc and use markdown. When we run the script, Compodoc creates a directory that we can commit to our repository. Thanks to that, we can not only serve the documentation locally but also deploy it. All of the above make Compodoc a valuable tool to create and view the NestJS documentation of our application.

Series Navigation<< API with NestJS #51. Health checks with Terminus and DatadogAPI with NestJS #53. Implementing soft deletes with PostgreSQL and TypeORM >>
Subscribe
Notify of
guest
3 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Dason
Dason
3 years ago

Will there be follow-up articles? I want to learn more

Lê Quốc Hùng
3 years ago

I appreciate it

Andri
Andri
3 years ago

Can we protect this doc with some kind of authorization like Swagger, where you have to insert a token to use other APIs aside from the login API?

Because we let our staging environment public so other third party front-end developers can use the swagger without accessing our backend code.