Api Docs v2.0-beta prototype for NestJS 😻 🚀

Hi 👋🏻, writing this post here a bit late due to some commitments in the last few days, but I wanted to announce that last Friday I made public an improved prototype of Api Docs for NestJS ( the v2.0-beta version ) developed by me and @brunnerlivio one of the NestJS core team members, at the moment not yet the official Api Docs, but hopefully one day it will become one 💪.

I attach some photos below:

Here is the link to access the Api Docs v2.0-beta for NestJS:

Link: https://api-references-nestjs.netlify.app 🔥 🚀

Lately we have also added a drop-down menu to switch between NestJS version 9 and version 10. 🙌

I add below some technical notes:

• The following official packages:

    * @nestjs/graphql
    * @nestjs/swagger
    * @nestjs/config
    * @nestjs/passport
    * @nestjs/jwt
    * @nestjs/mapped-types
    * @nestjs/cqrs
    * @nestjs/typeorm
    * @nestjs/sequelize
    * @nestjs/mongoose
    * @nestjs/serve-static
    * @nestjs/schedule
    * @nestjs/bull
    * @nestjs/elasticsearch
    * @nestjs/event-emitter
    * @nestjs/axios

do not have the @publicApi annotation, I added them manually.

Currently it is necessary to maintain and synchronize the forks of these packages( which I am managing), because we need to add the JSDoc @publicApi comments, so that the API generator knows what is considered an export that is part of the API, and it is a bit problematic to maintain.

Currently only the following packages have the JSDoc @publicApi annotation:

 - @nestjs/terminus
 - @nestjs/throttler
 - @nestjs/cache-manager 

In addition to the nest repository (https://github.com/nestjs/nest), where within the monorepository are the general and essential NestJS packages, which are as follows:

- @nestjs/common
- @nestjs/core
- @nestjs/microservices 
- @nestjs/platform-express
- @nestjs/platform-fastify
- @nestjs/websockets
- @nestjs/platform-ws
- @nestjs/platform-socket.io
- @nestjs/testing

I conclude by leaving you with this question:

Which official packages do you find most useful to have in the NestJS Api Docs?

• All packages ?

• Only in part (e.g., excluding those dedicated to ORMs, just to give a quick example) ?

This point is an open question on which I think it is fair for the entire community of developers using NestJS to give their input, in addition to the core team members, to decide which way to go.

Most probably this will be the last chance for NestJS to have its own Api Reference, not all frameworks have it it is true, but I think it is very useful for those who use NestJS and also for newcomers who are using NestJS.

There's always a saying, "Some 'opportunities' when they pass you have to jump at them."
NestJS is a great opportunity, let's not waste it. 💪

This "survey and discussion" however will go on for a while until the next major release of NestJS (v11.x), then we will consider whether to extend it.

I hope you can appreciate this work started by @brunnerlivio 4 years ago and carried on by me always with his supervision 🙌, and that it can be useful during your projects with NestJS.😻 🙏🏻 ( For more information about the "history" of this project as it started, see this PR: https://github.com/nestjs/docs.nestjs.com/pull/413)

That's it!
For anything write me in the comments 😉👍

Comments

[Костя Третяк]

API documentation like this is better suited for pure JavaScript projects. On TypeScript projects, such documentation reads quite well with an IDE such as VS Code.