DEV Community

Navidreza Abbaszadeh
Navidreza Abbaszadeh

Posted on

Automate Your API Docs Like a Pro with @nestjs/swagger

#automation #typescript #api #tutorial

Automate Your API Docs Like a Pro with @nestjs/swagger

Ever shipped an API and forgot to write the docs?
You’re not alone. Documentation is often the most painful part of backend development, yet the most essential one.

If you’re using NestJS, you already know how beautifully it structures your backend. But did you know you can generate Swagger documentation automatically with almost zero extra work?

Today, let’s dive into how you can use @nestjs/swagger to turn your NestJS code into interactive API docs, instantly.

Why Swagger?

Swagger (a.k.a. OpenAPI) isn’t just a “fancy UI”, it’s a machine-readable format for describing APIs.
That means tools, teams, and clients can understand your endpoints without reading your source code.

With Swagger you can:

  • Auto-generate docs with examples
  • Test your endpoints live in the browser
  • Share a single URL for both frontend devs and clients
  • Generate SDKs or clients in other languages (via OpenAPI generators)

Setting Up @nestjs/swagger

Let’s jump straight into it.

Install the package:

npm install --save @nestjs/swagger swagger-ui-express
Enter fullscreen mode Exit fullscreen mode

Then open your main.ts (the bootstrap file of your app) and add this snippet:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Awesome API')
    .setDescription('The API documentation for my awesome NestJS app')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();
Enter fullscreen mode Exit fullscreen mode

That’s it.
Now, run your app and head to: http://localhost:3000/api, boom, you’ve got a fully interactive Swagger UI.

Automating Swagger Decorators

Manually writing DTO decorators can get repetitive.
Here’s where @nestjs/swagger really shines, it reads metadata from your TypeScript types and decorators, automatically generating docs.

Example:

import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty({ example: 'john@example.com', description: 'User email' })
  email: string;

  @ApiProperty({ example: 'John Doe', description: 'Full name of the user' })
  name: string;
}
Enter fullscreen mode Exit fullscreen mode

Then, in your controller:

import { Controller, Post, Body } from '@nestjs/common';
import { ApiTags, ApiResponse } from '@nestjs/swagger';
import { CreateUserDto } from './create-user.dto';

@ApiTags('users')
@Controller('users')
export class UsersController {
  @Post()
  @ApiResponse({ status: 201, description: 'User created successfully.' })
  createUser(@Body() dto: CreateUserDto) {
    return { message: 'User created!', user: dto };
  }
}
Enter fullscreen mode Exit fullscreen mode

Swagger now automatically understands:

  • Request body
  • Tags
  • Response types
  • HTTP codes
  • Auth methods

All from your code.

Pro Tip: Auto-generate Swagger JSON

Want to automate everything, even your CI/CD pipeline?

You can export your OpenAPI JSON file directly:

import { writeFileSync } from 'fs';

const document = SwaggerModule.createDocument(app, config);
writeFileSync('./swagger-spec.json', JSON.stringify(document));
Enter fullscreen mode Exit fullscreen mode

Now your CI can upload swagger-spec.json to tools like:

  • Postman
  • Stoplight
  • SwaggerHub
  • Redocly

Boom, fully automated documentation that updates whenever your code does.

Bonus: Customizing Swagger UI

You can enhance your Swagger UI experience with extra options:

SwaggerModule.setup('docs', app, document, {
  swaggerOptions: {
    persistAuthorization: true,
    docExpansion: 'none',
  },
  customSiteTitle: 'My Awesome API Docs',
});
Enter fullscreen mode Exit fullscreen mode

This small touch makes your docs feel more professional and branded.

Summary

Step Action
1 Install @nestjs/swagger
2 Configure Swagger in main.ts
3 Use decorators in DTOs & Controllers
4 Optionally export swagger-spec.json
5 Automate updates via CI/CD

Wrapping Up

Documentation doesn’t have to be painful, with @nestjs/swagger, it’s automated, beautiful, and always up to date with your code.

Start using it today and make your API feel enterprise-ready with minimal effort.

Your turn:
Have you tried automating API docs in your NestJS project?
Drop your favorite Swagger tips in the comments below!

And if you found this post helpful,
follow me on Dev.to for fullstack development guides!

Top comments (0)