What?
Creating a NestJS application that serves as an OpenAPI (formerly known as Swagger) documentation for your RESTful API can be a valuable addition to your project. This allows you to automatically generate API documentation for your endpoints. Here's a step-by-step example of how to create a NestJS app with OpenAPI documentation:
Prerequisites:
- Node.js and npm installed.
- Basic knowledge of NestJS
Create a New NestJS Project:
If you haven't already, you can create a new NestJS project using the Nest CLI. Run the following command to generate a new NestJS application:
npx @nestjs/cli new nest-openapi-app
This will create a new NestJS project named nest-openapi-app
.
Install Required Dependencies:
Navigate to your project's root directory and install the required dependencies for OpenAPI and
validation. You will need @nestjs/swagger
and class-validator
for
this:
npm install --save @nestjs/swagger
Setup OpenAPI Configuration:
In your NestJS project, create an openapi.config.ts
file in the root directory. This
file will contain the OpenAPI configuration:
import { DocumentBuilder } from '@nestjs/swagger';
export const openapiConfig = new DocumentBuilder()
.setTitle('Your API Title')
.setDescription('Your API Description')
.setVersion('1.0')
.addTag('Your API Tag')
.build();
Main Application Module:
In your main application module (usually app.module.ts
), import the
SwaggerModule
and openapiConfig
that we defined earlier:
import { Module } from '@nestjs/common';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { openapiConfig } from './openapi.config'; // Import your OpenAPI config
@Module({
imports: [
// Other modules and services
],
})
export class AppModule {
constructor() {
const document = SwaggerModule.createDocument(this.app, openapiConfig);
SwaggerModule.setup('api', this.app, document);
}
}
Decorate Controllers and Routes:
In your controller classes and route handlers, use decorators from @nestjs/swagger
to specify metadata for OpenAPI documentation. For example:
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
@Controller('users')
@ApiTags('Users')
export class UsersController {
@Get()
findAllUsers() {
return 'List of users';
}
}
Here, @ApiTags is used to specify a tag for this route, which will be displayed in the OpenAPI documentation.
Access OpenAPI Documentation:
Your OpenAPI documentation should now be accessible at http://localhost:3000/api
.
This page will display all the endpoints and details you specified in your code, thanks to the
@nestjs/swagger decorators.
This is a basic example of how to set up OpenAPI documentation in a NestJS application. You can further customize your documentation by using more Swagger decorators and adding additional information in your openapi.config.ts file. This approach helps in keeping your API documentation in sync with your actual code, making it easier to maintain and share with others.