Integrating Swagger with NestJS: A Step-by-Step Guide
API development often requires a clear visual representation and testing mechanism for endpoints. This is where Swagger, an open-source tool, comes into play. If you’re working with NestJS — a progressive Node.js framework — you’re in luck! The integration of Swagger is seamless and powerful. Let’s explore how to do this.
Why Swagger?
Swagger offers a set of tools for designing, building, and documenting RESTful APIs. The most notable of these tools is Swagger UI, which provides a visual platform to interact with the API’s endpoints without any integrated front end.
Prerequisites
Basic knowledge of TypeScript and NestJS.
A NestJS project setup. If you don’t have one, you can set it up using the Nest CLI.
Step-by-Step Integration
1. Installing Required Packages:
Start by installing the necessary libraries:
npm install @nestjs/swagger swagger-ui-express
2. Setting Up Swagger:
Navigate to your main file (typically main.ts) and set up Swagger:
With this setup, your Swagger UI will be available at http://localhost:3000/api-docs.
3. Annotating APIs with Swagger Decorators:
NestJS provides decorators that integrate seamlessly with Swagger to auto-generate documentation.
a) Controllers and Routes:
Decorate your controllers and routes with appropriate Swagger decorators:
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
@ApiTags('User')
@Controller('user')
export class UserController {
@Get()
findAllUsers(): string {return this.userService.findAll();
}
}
4. Explore and Test:
Swagger UI isn’t just for documentation. Use it to test your endpoints directly from the browser. This becomes especially handy when debugging or when providing examples to frontend teams.
Document the Project Created using swagger:
To document the Swagger API in NestJS, we need to use the @nestjs/swagger module. It appears you already have the Swagger integration set up in our main.ts and library.controller.ts files.
Once you have set up Swagger in your NestJS application and your server is running, you can view the Swagger documentation by navigating to the Swagger UI endpoint. By default, this endpoint is configured in the SwaggerModule.setup method in your main.ts file.
In the provided code:
SwaggerModule.setup('api-docs', app, document);
Let's start by documenting your Book model. Assuming your Book model is a class with properties, you can use the @ApiProperty decorator to describe each property.
Next, let's make sure your LibraryController and its endpoints are well-documented. I'll enhance the Swagger documentation for each endpoint.In this example, I added type: Book to @ApiResponse for each endpoint to indicate the expected response type. Additionally, for the fetchAll endpoint, I added isArray: true to indicate that it returns an array of books.
You can also use the @ApiResponse decorator to document the response types for each API endpoint. I'll modify your LibraryController to include response types in Swagger like this :
Conclusion:
Swagger and NestJS go hand in hand when it comes to building professional, clear, and interactive APIs. With just a few decorators, you can transform your API documentation from plain text to an interactive playground. Not only does this enhance developer experience, but it also ensures that everyone interacting with your API — be it frontend developers, QA teams, or stakeholders — has a clear understanding of its functionality. Happy documenting! 🚀
Top comments (1)
Exciting journey into Nest JS! Integrating Swagger for API documentation is a game-changer. Can't wait to explore and streamline the development process further