Swagger API documentation in NestJS - Mini Project: Build & Apply

Swagger API documentation

📖 Scenario: You are building a simple NestJS API for managing books in a library. You want to add Swagger API documentation so that other developers can easily understand and test your API endpoints.

🎯 Goal: Create a NestJS controller with Swagger decorators to document the API endpoints for getting all books and adding a new book.

📋 What You'll Learn

Create a controller named BooksController

Add a GET endpoint /books that returns a list of books

Add a POST endpoint /books that accepts a book object

Use Swagger decorators @ApiTags, @ApiOperation, and @ApiResponse to document the endpoints

Define a DTO class CreateBookDto with title and author properties and document it with @ApiProperty

💡 Why This Matters

🌍 Real World

Swagger documentation helps developers understand and test APIs easily without guessing endpoints or request formats.

💼 Career

Knowing how to add Swagger docs is a common requirement for backend developers working with NestJS or other frameworks to improve API usability.

1

Create the initial data structure

Create a class called CreateBookDto with two string properties: title and author. Use @ApiProperty() decorator from @nestjs/swagger on both properties.

NestJS

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

// Create the CreateBookDto class with title and author properties
// Your code here

Hint

Use export class CreateBookDto and add @ApiProperty() above each property.

2

Add Swagger tag configuration

Create a controller class called BooksController and add the @ApiTags('books') decorator from @nestjs/swagger above it.

NestJS

import { Controller } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';

// Create BooksController with @ApiTags('books') decorator
// Your code here

Hint

Use @ApiTags('books') and @Controller('books') above the BooksController class.

3

Add GET and POST endpoints with Swagger documentation

Inside BooksController, add a GET method called getAllBooks with @Get() decorator and Swagger decorators @ApiOperation({ summary: 'Get all books' }) and @ApiResponse({ status: 200, description: 'List of books returned.' }). Also add a POST method called createBook with @Post() decorator, Swagger decorators @ApiOperation({ summary: 'Add a new book' }) and @ApiResponse({ status: 201, description: 'Book created.' }), and accept a parameter createBookDto of type CreateBookDto decorated with @Body().

NestJS

import { Get, Post, Body } from '@nestjs/common';
import { ApiOperation, ApiResponse } from '@nestjs/swagger';

// Add getAllBooks method with GET and Swagger decorators
// Add createBook method with POST, Swagger decorators, and @Body() parameter
// Your code here

Hint

Use @Get() and @Post() decorators with matching method names and add Swagger decorators as shown.

4

Complete the Swagger setup in main.ts

In the main.ts file, import SwaggerModule and DocumentBuilder from @nestjs/swagger. Create a Swagger document with DocumentBuilder() setting the title to 'Library API', description to 'API for managing books', and version to '1.0'. Then call SwaggerModule.setup('api', app, document) to serve the docs at /api. Assume app is the NestJS application instance.

NestJS

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

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

  // Setup Swagger documentation here
  // Your code here

  await app.listen(3000);
}
bootstrap();

Hint

Use DocumentBuilder to create config and SwaggerModule.setup to serve docs at /api.

Practice

1. What is the main purpose of using Swagger in a NestJS application?

easy

A. To automatically generate interactive API documentation

B. To improve database query performance

C. To handle user authentication

D. To manage application state

Solution

1. Step 1: Understand Swagger's role

   Swagger is a tool that creates easy-to-read and interactive API documentation automatically.

2. Step 2: Compare options

   The other options relate to database performance, authentication, and state management, which Swagger does not handle.

3. Final Answer:

   To automatically generate interactive API documentation -> Option A

4. Quick Check:

   Swagger = API docs [OK]

Hint: Swagger = auto API docs, not database or auth [OK]

Common Mistakes:

• Confusing Swagger with authentication tools
• Thinking Swagger improves database queries
• Assuming Swagger manages app state

2. Which NestJS class is used to configure the API information for Swagger documentation?

easy

A. HttpModule

B. SwaggerModule

C. ApiProperty

D. DocumentBuilder

Solution

1. Step 1: Identify configuration class

   DocumentBuilder is the class used to set API title, description, version, and other info for Swagger.

2. Step 2: Differentiate from other classes

   SwaggerModule sets up the docs route, ApiProperty decorates DTO properties, HttpModule handles HTTP requests.

3. Final Answer:

   DocumentBuilder -> Option D

4. Quick Check:

   API info config = DocumentBuilder [OK]

Hint: DocumentBuilder builds API info for Swagger [OK]

Common Mistakes:

• Confusing SwaggerModule with DocumentBuilder
• Using ApiProperty for API config instead of DTO properties
• Thinking HttpModule configures Swagger

3. Given the following NestJS Swagger setup code, what URL will serve the Swagger UI?

const config = new DocumentBuilder()
  .setTitle('Cats API')
  .setDescription('API for cats')
  .setVersion('1.0')
  .build();

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

medium

A. http://localhost:3000/api-docs

B. http://localhost:3000/swagger

C. http://localhost:3000/docs

D. http://localhost:3000/api

Solution

1. Step 1: Identify the setup path

   The setup method uses 'api-docs' as the first argument, which defines the URL path for Swagger UI.

2. Step 2: Combine with default host and port

   By default, NestJS runs on localhost:3000, so the full URL is http://localhost:3000/api-docs.

3. Final Answer:

   http://localhost:3000/api-docs -> Option A

4. Quick Check:

   SwaggerModule.setup path = api-docs [OK]

Hint: First argument in setup() is Swagger URL path [OK]

Common Mistakes:

• Assuming default path is /swagger or /docs
• Confusing createDocument with setup URL
• Ignoring the string passed to setup()

4. Identify the error in this NestJS Swagger setup code:

const config = new DocumentBuilder()
  .setTitle('Dogs API')
  .setDescription('API for dogs')
  .setVersion('1.0')
  .build();

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

medium

A. SwaggerModule.setup path should be '/swagger' not 'docs'

B. Missing call to build() on DocumentBuilder

C. The order of arguments in createDocument is incorrect

D. DocumentBuilder cannot set version

Solution

1. Step 1: Check createDocument arguments

   The correct order is (app, config), but here it is (config, app), which causes an error.

2. Step 2: Verify other parts

   build() is called correctly, setup path 'docs' is valid, and DocumentBuilder can set version.

3. Final Answer:

   The order of arguments in createDocument is incorrect -> Option C

4. Quick Check:

   createDocument(app, config) order matters [OK]

Hint: createDocument(app, config) order is fixed [OK]

Common Mistakes:

• Swapping app and config in createDocument
• Forgetting to call build() on DocumentBuilder
• Thinking setup path must be '/swagger'

5. You want to add a global prefix '/api' to all routes in your NestJS app but still serve Swagger docs at '/docs'. Which setup correctly achieves this without breaking Swagger access?

hard

A. Do not set global prefix; use SwaggerModule.setup('docs', app, document);

B. app.setGlobalPrefix('api'); SwaggerModule.setup('docs', app, document);

C. app.setGlobalPrefix('api'); SwaggerModule.setup('api/docs', app, document);

D. SwaggerModule.setup('api/docs', app, document); app.setGlobalPrefix('api');

Solution

1. Step 1: Understand global prefix effect

   Setting a global prefix like 'api' adds it to all routes except those explicitly set in SwaggerModule.setup.

2. Step 2: Confirm Swagger path independence

   SwaggerModule.setup('docs', app, document) serves docs at '/docs' ignoring global prefix, so docs remain accessible.

3. Step 3: Analyze other options

   Other sequences either omit the global prefix or incorrectly include it in the Swagger path, leading to double prefixing or wrong Swagger location.

4. Final Answer:

   app.setGlobalPrefix('api'); SwaggerModule.setup('docs', app, document); -> Option B

5. Quick Check:

   Global prefix separate from Swagger path [OK]

Hint: Set global prefix separately; Swagger path stays independent [OK]

Common Mistakes:

• Adding global prefix inside Swagger path causing double prefix
• Not setting global prefix when needed
• Changing Swagger path to include global prefix unnecessarily