[WIP] API Docs

[BrunnerLivio]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/docs.nestjs.com/blob/master/CONTRIBUTING.md

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] Other... Please describe:

What is the current behavior?

No detailed API documentation

Issue Number: #249

What is the new behavior?

Adds an API page which displays detailed information of all the exposed classes / constants / interfaces / etc. of NestJS.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

• The code is highly inspired by the angular repository
• To generate the doc pages from the source code it uses a tool called dgeni.
• This PR will introduce git submodules, so dgeni can generate the pages from the code
• It is far from finished - Just want to involve you into the process asap :)
• This PR will get big without a doubt :/
• URLs in code (cross-references of types for example) will get overwritten by Prism highlighter - we need to find a workaround / other library, because URL in code would be super helpful for the user.

[BrunnerLivio]

It is getting better and better ;)

[1valdis]

Any ETA on that? I'm coming from Sequelize which has full API reference, and I'm having a hard time understanding what I'm working with not having API reference, considering myriad of packages and whatever Nest has :(

[priyashpatil]

@kamilmysliwiec what's eta for this. Waiting for it.

[BrunnerLivio]

Waiting for #969, so I can implement dynamic routing and then revisit this PR. It depends on all those things.

[tonivj5]

@BrunnerLivio #969 was reverted. Is there any plan to continue with this PR? Really good work! 🚀

[knownasilya]

Really interested in this as well.

[BrunnerLivio]

I'd love to revisit this PR, though my day-to-day job is taking all of my energy at the moment.

Though in case you're interested to contribute to it, here are some hints about my strategy;

The main reason why this PR is frozen is that it needs quite some underlying change related to routing. My aim was to basically implement a similar architecture as the Angular documentation.

In summary, the way the Angular documentation works is that it generates documents from various data sources (e,g, markdown, or typescript files) and translates it to HTML. This is mostly already done in this PR -- meaning you can expect that there are static HTML files that contain all the information about all the classes which exist in NestJS.

Now the part which I was unable to finish so far:
This content needs to be dynamically displayed on the documentation. Meaning if the user for example requests docs.nestjs.com/api/core/logger, the documentation will need to look after a local file in static/core/logger.html and place the contents inside the main body of the website.

Sounds easier than it actually is. On of the reason for that is that the HTML files can contain Angular components (e.g. for displaying the code). Angular components can not load dynamically when you load an external HTML content and place it via e.g. innerHTML into the DOM. What the Angular team has done, they converted all their Angular components which can be placed into the DOM to Web Components using Angular Elements. That is why I started for example #1214.

On top of that, the Angular team has written its own router, since @angular/router does not provide the capability of having such dynamic content. They even dynamically load the Web Components, depending on which HTML document will be displayed on the docs. Meaning the user does not need to load unnecessary JS. But that is not mandatory to implement in the case of the NestJS docs in my opinion.

Now steps forwards;

I think it would make sense to have a closer look at Scully. I haven't gotten my hands dirty with it yet, but in case it works similar to GatsbyJS, then it is definitely something we should use in order to make this PR happen. With that we could by-pass all of the routing stuff mentioned above.

So in short; I'd love to see a PoC with Scully and see whether this person could dynamically create pages using HTML content provided by this PR with Angular components from the NestJS docs.

Depending on the PoC, I think we should then either pursue it or re-visit the "Angular documentation"-approach

[BrunnerLivio]

Someone just asked me privately how to run this branch locally in 2022.

Here are updated instructions:

1. Some dependencies are quite outdated and use http-based connection with Github. To fix this, add this to your .gitconfig. Read more here

[url "https://"]
    insteadOf = git://

2. Execute these commands in your Terminal (make sure you have nvm installed):

git clone -b feature/api-docs [email protected]:BrunnerLivio/docs.nestjs.com.git
nvm use 10
cd docs.nestjs.com
npm ci
cd sources/
git clone [email protected]:nestjs/terminus.git 
# Clone other nestjs/* repos in case you need them
cd ..
npm start

[vahidvdn]

Any update on this?

[joaquinnunez]

i guess, i'll have to clone the project and git grep my way to read the api reference, sad this is not live

[knownasilya]

Is nestjs abandoned?

[jmcdo29]

Is nestjs abandoned?

@knownasilya what gave you that idea? Kamil is literally working on the v10 branch and has been for the past few weeks. Just because this API docs that was an experimental branch hasn't been merged does not mean it's anywhere close to abandoned.

[knownasilya]

Wasn't aware of v10 work, seems that api reference docs would be ultra high priority for a project like this.

[knownasilya]

BTW @jmcdo29 you have always been very helpful whenever I had questions, so thanks!

[kamilmysliwiec]

You can navigate to this repository https://github.com/nestjs/nest, press . and search for @publicApi. How's this page ultra priority given all the other tooling we have in 21st century?

[1valdis]

Question is not just having the list of public API; without proper description for each entry it's just a small part of the solution. All of the APIshould be properly documented as well. For example, there's a very interesting thing in Core called DiscoveryService. How a developer is supposed to learn how it works and what it can be used for? By reading the source? Or other repositories which are built upon it? That's suboptimal.

[kamilmysliwiec]

I agree that there're still things we should document better, but that was not the point of my comment above.

[1valdis]

Regarding you comment above, Kamil: I personally didn't know one could press . and open and editor; and also I didn't know I should search for @publicApi and that would be the list of everything that's intended for users. Is this documented somewhere other than in this issue at this point?

[Tony133]

Hi everyone, 😀 👋🏻

Since many people ask me if the PR will be continued, also to reassure and clarify the situation, I wanted to announce that the new version of the Api Docs (v2.0 beta) for NestJS 😻 ♥️ 🚀 is coming. There has been a handover between me and Livio and I decided to "take over" this PR as a contributor to the NestJS project to improve and complete it and make it work on the latest versions of Angular and NodeJS, following the basics that Livio had set up to help the NestJS Core Team to document NestJS even better, I have been working on it for months in my spare time however Livio is always up to date on all the steps so far ( my supervisor ♥️ ) we exchanged ideas and ways on how to improve it.

I will start by anticipating a few things:

• At the moment it will not be integrated into the official documentation as per PR, but in a separate App (also because of the dark mode), so we can gather feedback and notes on how to improve it over time. Once it is "live," the idea is to open a post on discord so that we can collect all the feedback from all the people there, so that the NestJS Core Team does not have many notifications on Github.
  So as to understand if it is really useful for developers who use NestJS also to be more determined whether to continue development or not.

• The Api Docs is generated based on what is written and commented in the NestJS code, based on the @publicApi annotation, so in many apis you will find empty descriptions because no comments are written in the code. However this can be useful for contributors and new people who want to contribute to NestJS and also for core team members to figure out where to comment code in the official NestJS packages, so as to add more complete descriptions and later they are generated in the APIs Docs.

• Then there would also be figuring out which packages the community at large or the Core Team wants exposed in the Api Docs.( I will talk about this on the day of the launch date ).

I would like to take this opportunity to heart thank @BrunnerLivio ♥️ for the help and the path taken to develop the new version without the code base started and done 4 years this new version would not exist.
The new version was developed "under-track" because free time is always short, also due to private and personal commitments we wanted to take things slowly, without rushing.

We hope this work of ours will help people using NestJS to better understand the framework and be a great starting point for the Api Docs for NestJS 🙌 .

I also repeat it here, The biggest work is to be done in the official NestJS repositories so that more detailed descriptions can be added.

Perhaps I was a little long in my description, but I wanted to start by specifying a few points well. 🙏🏻

I conclude by attaching some photos of how it looks now (screenshot taken in dark mode) 😎.

coming soon, the story continues 👀........ 🙌

[knownasilya]

Thanks for clarifying @Tony133, looking forward to it

[Tony133]

Hi all 😀 👋🏻, as promised, 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 as described in the previous post:

• 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), 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 an Api Docs for NestJS ?

• All packages ?

• Just a few (e.g., excluding those dedicated to ORMs, just as 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, as well as members of the core team, to decide which way to go.

Most likely 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 it.

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

This "poll and discussion" however will go on for a while until the next major release of NestJS (v11.x), then we will see if we extend it further.

Mark this date: July 7, 2023, NestJS to a working prototype of Api Docs as a great starting point, hoping that one day it will become the official one. 😻 ♥️

I have gone on and on in this post, but I like to specify things well 😄. 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.😻 🙏🏻

P.s: We are considering whether to open a post on the Discord support channel to move all feedback maybe there, we are still considering with @BrunnerLivio how to proceed. In case of updates we will write you! 😉👍

[Tony133]

Two small updates 👀:

In these weeks after the launch, I also made a DEV.to post about this prototype see here: https://dev.to/tony133/api-docs-v20-beta-prototype-for-nestjs-3jdj , so it would be even more visible 🚀 🌎, and I also created a thread in the discord support channel (direct link to the thread): https://discord.com/channels/520622812742811698/1128439541326417962 💪

That is all 😉 👍

[c3cris]

Every framework I know documents its API, this should be a priority.