Made withNestJSClip

19 Nest JS JWT Swagger API documentation setup

A

Amitav Roy

Creator on the NestJS channel

Watch on YouTube ↗

30K viewsApr 26, 202212:29 runtime

Learn how to seamlessly integrate Swagger to create beautiful, interactive API documentation for your NestJS application. This guide walks you through the entire process, from installing the necessary npm modules to configuring Swagger in your `main.ts` file. Discover how to use…

Chapters

#nestjs#clip#backend

Why Use Swagger with NestJS?

Swagger provides a powerful way to automatically generate beautiful and interactive API documentation directly from your NestJS codebase.

Seamless Integration: NestJS offers a dedicated module (@nestjs/swagger) that integrates smoothly with its architecture.
Automatic Documentation: It reads your controllers, DTOs, and models to build a comprehensive API reference.
Interactive Testing: Allows developers to test API endpoints directly from the browser, which is useful for validation and debugging.

Initial Setup & Configuration

Install Dependencies: Add the required packages to your project.
```
npm install --save @nestjs/swagger swagger-ui-express
```
Important
Before installing Swagger, ensure your project's other dependencies are updated to their latest versions to avoid compatibility issues. The video references a specific Git tag for a stable, updated starting point.
Configure in main.ts: In your main application file, set up and mount the Swagger UI.
- Use the DocumentBuilder class to create a base configuration with metadata like the API's title, description, and version.
- Call SwaggerModule.createDocument(), passing in your app instance and the builder config.
- Call SwaggerModule.setup() to mount the Swagger UI on a specific path (e.g., /api), passing it the app instance and the generated document.

Documenting Endpoints

To enrich the basic documentation, use decorators to add detailed information about your endpoints.

Request Body Schemas

Use the @ApiProperty() decorator on each property within your DTO (Data Transfer Object) files. This tells Swagger about the fields expected in a request body, including their names and types, which it uses to generate an example schema.

API Responses

Documenting what your API returns is crucial. This involves two steps:

Decorate the Controller Method: Use response decorators like @ApiCreatedResponse(), @ApiOkResponse(), or @ApiBadRequestResponse() on your controller methods. You can add a description for each potential status code.
Define the Response Shape: Inside the response decorator, use the type property to specify the DTO or entity that represents the response body (e.g., type: UserEntity). Then, add @ApiProperty() decorators to the properties of that entity/DTO to define the response payload's schema.

Tip

Grouping API Routes

As your application grows, you can organize your endpoints by adding the @ApiTag('TagName') decorator at the top of a controller class. This groups all routes within that controller under a specific, collapsible section in the Swagger UI, making navigation much cleaner.

Interactive API Testing

One of Swagger's most powerful features is the "Try it out" button available on every endpoint. This allows you or other API consumers to:

Fill in request parameters and body content.
Execute the API call directly from the documentation browser.
See the exact cURL command, response code, and response body.

This is an invaluable tool for validating and testing your API logic before handing it over to a front-end team.

Introduction & Initial Setup

Hey, what's up, guys? Today, in this video, we are going to look at how to go ahead and install Swagger so that we can have a nice looking documentation for our API. It's a very seamless integration with NestJS when you write your routes and your controller has basic definitions, which will in the end allow you to create that beautiful Swagger documentation. So let's get started.

I will follow the instructions which are present in the documentation for the installation part. Okay? It's quite straightforward. We first install these npm modules, okay, and then we have a little bit of configuration for Swagger to start on a particular URL. And then I'll show you how we configure every model, every DTO, and controller to get certain information on Swagger.

In the meantime, I would like to tell you one thing. I have updated the dependencies of this application to the latest level. So if you go to GitHub and let us say this is the URL, right? So I have created a tag where if you go to 001, this is the version where I have the latest dependencies. And if you go to my commits, you will see this version has all the updates, right? And I would strongly suggest that when you are installing Swagger, you first should get the latest version of the code. And once done, only then go with the Swagger installation.

So my Swagger npm modules are installed.

Configuring Swagger in `main.ts`

Then there is a little bit of configuration. I will just steal this piece of code from here, go to main.ts, and maybe paste a few things over here. And let's add all missing imports. So what are we doing? Let's quickly look at these things.

So we are building a configuration variable from DocumentBuilder. That's fine. So these are some of the parameters, for example, setTitle, setDescription, version, and build. Okay. With this configuration, what we have done is we created one more variable called document. We call the SwaggerModule.createDocument where we pass the app. This is the Nest app; if you see, it must be taking the INestApplication. Right? So we pass the app as the first parameter and config as the second, and we get a document.

And then in the end, we are saying SwaggerModule.setup. api—this is the URL which you can have anything, my-api or swagger, something like that. I will keep it as api, it feels better. And we are passing the app and we are passing this document that we just created.

With this in place, the first thing which is going to happen is on your app, which is running on localhost:3000, I'll start seeing this thing. Okay, this is my title and this is the description and these are all the routes which are present inside my application.

Defining Request Body Schemas with DTOs

So now if we go into the register method, for example, right? This should ideally be the first way of sharing the API. So let's just say the front-end developer is working on building the UI and you said, "Okay, this is the URL. You can go to Swagger and see what kind of request body is being expected and what kind of responses you are going to get."

Now at this moment, there is nothing in it for the front-end developer to understand, but you will see very soon with some basic changes, I will be able to create a nice looking documentation over here. So let's see.

I'll go to my code. The first thing is obviously go to UserController. The registration URL is taking the UserRegisterRequestDTO. So first of all, we will add certain properties in our DTO for Swagger to show them on the documentation page. For example, right now, it doesn't show anything in the schema. It just says user registration DTO is being used, correct?

But if we do @ApiProperty and add a few properties to it... So with this done, if I now refresh, can you see that it shows me what kind of parameters are required? And if I actually try, the JSON gets filled up with name. So let's fill the other details as well.

All right, so I have populated the @ApiProperty on all the items and now if I refresh, can you see this is getting populated, right?

So at least now we have a clear documentation of what is the request body that is required by the front-end developer or anyone to send so that our user can register.

Documenting API Responses and Status Codes

But now, there is also one more thing, which is we need to show the response, right? Because that's also very important. So how do we do that? Let's go to our UserController. Inside the UserController, let's just add... so we have @ApiResponse, and then we have other kinds of properties as well.

I'll quickly show you in the documentation where to find all of them. I think it's somewhere... operations... yes, responses. I think it's the responses. If you see, @ApiOkResponse, @ApiCreatedResponse, @ApiAcceptedResponse, so on and so forth. Even a @BadRequest and unauthorized responses are available.

What we want to do over here is, first of all, an @ApiCreatedResponse. So let me see. This is our @ApiCreatedResponse. If you go inside them, you will see all the keys which are available which you can fill in. I'll just add the description, okay? Something like this.

And if I go over here, let's just say this thing can fail, right? So maybe what I will do is add a bad request as well. So @ApiBadRequestResponse. This is bad gateway, this is bad response, right? And maybe add a description again over here, which is, "User cannot register. Try again." Something like that.

With this, now let's refresh our Swagger UI and see what is happening. So now can you see this is the request body, this is the response, and the response is 'Created user object as response'. 201 is a status code which I can expect, 400 is a user code which I expect, which is fine. But there is no response object or, to say, there's no defined JSON data which I can understand I'll be getting as a UI developer in response when the user has registered. Right? So let's see how we can add that.

So in here, there is a property called type, and in that I can add the type of object I'm expecting. With this, now can you see this thing changed? I'm saying that this is the kind of data which will come in. But obviously, I imported the model, right, the entity, but the entity doesn't have any definition to it. And if I quickly add them, you will see that these things will come up. So let's quickly add that. Again, these will be @ApiProperty.

Okay, so I have all the properties added over here. I haven't added the created and updated column. Let's see now what comes up over here. Right, so I can see all this stuff. Maybe I'll just add @ApiProperty... these two items as well and see what comes up. Right, so the dates are coming. So generally speaking, we are able to get the entire thing.

Testing Endpoints with the Swagger UI

So this entire documentation is kind of done. If you see the registration gives me the request body, responses, and the beautiful thing is if I try to use this, maybe just try to register the user... Let me open up my database as well. Right, so this is my database. I have only one user. Let's go over here and execute. Okay, this is done. This is the cURL command which got executed, and in the response, I got this ID. Let's see. Perfect. So we have this in place and this basically means I can use this Swagger documentation to not only interact with my API but also give it as a documentation.

Grouping API Routes with Tags

And one last thing which I would like to tell you is there is right now this default thing. If you see, there are schemas, we have all the DTOs, we have our model definition as well, but everything over here is inside default, right? But we can divide them, we can group them into different kinds of API stuff. I mean, for example all the user routes may go inside one particular thing. So for that, what you can do is go inside your controller. I'll go inside my controller and over here where you have this controller definition, right, you can do @ApiTag and just add 'user' to it.

With this done, if I now refresh, can you see that particular API came inside the 'user' thing? So for example, if I go to quiz, the quiz controller... and @ApiTag, add 'quiz', hit refresh. Oops. So all the three URLs or the API routes which are present inside this controller goes in that particular group or that tag. So we are able to visually kind of bifurcate all the different kinds of routes, and so you can quickly navigate to them if required. So, you know, when your application grows, you will definitely have a lot of routes and it makes sense to tag them and group them logically.

Conclusion & Key Takeaways

So yes, this is what swagger documentation help you with. I find this tool to be very interesting and I really use it a lot. It not only allows me to create a documentation, so as to say, for my APIs, but it also allows me to actually test the API calls because I can always go into the 'Try it out' and register a user, see whether the thing is working properly or not, and validate whatever is done before passing on the API to the front-end team to work on.

So yeah, this is typically what I do and that's why I like it. Let me know what are your thoughts about this thing. If you like this video, do click on the thumbs up icon and yes, don't forget to subscribe to my channel.