Swagger API documentation in NestJS - Step-by-Step Execution

Concept Flow - Swagger API documentation

Start NestJS App

↓

Import SwaggerModule

↓

Create Swagger Document

↓

Setup Swagger UI Route

↓

Run App

↓

Access Swagger UI in Browser

This flow shows how NestJS app imports Swagger, creates API docs, sets up UI route, and serves docs.

Execution Sample

NestJS

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

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

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

This code creates Swagger docs for a NestJS app and sets up the '/api' route to show the docs UI.

Execution Table

Step	Action	Input/Parameters	Output/Result
1	Import SwaggerModule and DocumentBuilder	None	Modules ready to use
2	Create DocumentBuilder config	Title='Cats API', Description='API for cats', Version='1.0'	Config object with metadata
3	Build config	Config object	Final config for Swagger
4	Create Swagger document	App instance, config	Swagger JSON document describing API
5	Setup Swagger UI route	Route='api', app, document	Route '/api' serves Swagger UI
6	Run app	App instance	App runs with Swagger UI available
7	Access Swagger UI	Browser at '/api'	Interactive API docs shown

💡 Swagger UI is ready and accessible at '/api' route after app runs

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
config	undefined	DocumentBuilder instance with title, description, version	Built config object	Passed to createDocument	Used to generate Swagger JSON
document	undefined	undefined	undefined	Swagger JSON document	Used in SwaggerModule.setup

Key Moments - 3 Insights

Why do we need to call .build() on DocumentBuilder?

The .build() method finalizes the config object. Without it, SwaggerModule.createDocument won't get the correct metadata. See execution_table step 3.

What does SwaggerModule.setup() do exactly?

It creates a route in the app (like '/api') that serves the Swagger UI with the generated docs. See execution_table step 5.

Can I access Swagger UI before running the app?

No, the app must be running to serve the Swagger UI route. See execution_table step 6 and 7.

Visual Quiz - 3 Questions

Look at the execution table, what is the output of step 4?

A Route '/api' serving Swagger UI

B Swagger JSON document describing the API

C DocumentBuilder instance

D App instance running

💡 Hint

Check the 'Output/Result' column in step 4 of execution_table

At which step is the Swagger UI route '/api' set up?

A Step 5

B Step 3

C Step 6

D Step 7

💡 Hint

Look for 'Setup Swagger UI route' action in execution_table

If you forget to call .build() on DocumentBuilder, what happens?

A App will not run

B Swagger UI route will be '/docs' instead of '/api'

C SwaggerModule.createDocument gets incomplete config

D No effect, docs generate normally

💡 Hint

Refer to key_moments about .build() importance and execution_table step 3

Concept Snapshot

Swagger API docs in NestJS:
- Import SwaggerModule and DocumentBuilder
- Use DocumentBuilder to set title, description, version
- Call .build() to finalize config
- Create document with SwaggerModule.createDocument(app, config)
- Setup UI route with SwaggerModule.setup('api', app, document)
- Run app and visit '/api' to see docs

Full Transcript

This visual execution trace shows how to add Swagger API documentation to a NestJS app. First, you import SwaggerModule and DocumentBuilder. Then you create a config with title, description, and version using DocumentBuilder and call .build() to finalize it. Next, you create a Swagger document from the app and config. After that, you set up the Swagger UI route, usually '/api', so the docs are accessible in the browser. Finally, you run the app and open the browser at '/api' to see interactive API documentation. Key points include the need to call .build() and that the app must be running to serve the docs.

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