Swagger API documentation in NestJS - Performance & Optimization

Performance: Swagger API documentation

MEDIUM IMPACT

This affects the initial page load speed and bundle size by adding metadata and UI assets for API docs.

Serving API documentation in a NestJS app

NestJS

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

const config = new DocumentBuilder()
  .setTitle('API')
  .setDescription('API docs')
  .setVersion('1.0')
  .build();
const document = SwaggerModule.createDocument(app, config);
if (process.env.NODE_ENV === 'development') {
  SwaggerModule.setup('api', app, document);
}

Only enables Swagger UI in development, avoiding extra assets and render blocking in production.

📈 Performance GainSaves ~300kb in production bundle, improves LCP by avoiding render-blocking UI

Serving API documentation in a NestJS app

NestJS

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

const config = new DocumentBuilder()
  .setTitle('API')
  .setDescription('API docs')
  .setVersion('1.0')
  .build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);

This loads the full Swagger UI and JSON docs on every app start, increasing initial bundle size and blocking rendering.

📉 Performance CostAdds ~300kb to bundle, blocks rendering for 100-200ms on initial load

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Full Swagger UI always loaded	High (many UI nodes)	Multiple reflows on load	High paint cost due to UI	[X] Bad
Swagger UI loaded only in development	Low (no UI in prod)	No reflows in prod	Minimal paint cost in prod	[OK] Good

Rendering Pipeline

Swagger UI assets and JSON docs are loaded after initial HTML, triggering style calculation, layout, paint, and composite steps. Large JSON or UI scripts increase load and block rendering.

→Style Calculation

→Layout

→Paint

→Composite

⚠️ BottleneckPaint and Composite due to large UI scripts and styles

Core Web Vital Affected

LCP

This affects the initial page load speed and bundle size by adding metadata and UI assets for API docs.

Optimization Tips

1Only enable Swagger UI in development or behind authentication to avoid extra load in production.

2Minimize Swagger JSON size to reduce parsing and rendering time.

3Use lazy loading or conditional setup to prevent blocking the main thread.

Performance Quiz - 3 Questions

What is the main performance impact of including Swagger UI in a NestJS app?

A Increases initial bundle size and blocks rendering

B Improves API response time

C Reduces server CPU usage

D Decreases network latency

DevTools: Network

How to check: Open DevTools, go to Network tab, filter by JS and JSON, reload page and observe Swagger UI assets loading

What to look for: Look for large Swagger UI JS and JSON files loading and blocking main thread; absence in production indicates good performance

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