Adding OpenAPI to NestJS App

Adding OpenAPI to NestJS App | Time Saving

20 min read

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.

This is me…