Swagger API documentation in NestJS

Introduction

Swagger helps you create clear and easy-to-read API docs automatically. It shows what your API can do and how to use it.

You want to share your API with other developers clearly.

You need a simple way to test your API endpoints.

You want to keep your API docs updated automatically as you change code.

You want to generate client code or SDKs from your API docs.

You want to improve communication between frontend and backend teams.

Syntax

NestJS

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

const config = new DocumentBuilder()
  .setTitle('API Title')
  .setDescription('API description')
  .setVersion('1.0')
  .build();

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

Use DocumentBuilder to set your API info like title and version.

Call SwaggerModule.setup() to serve the docs at a URL (e.g., '/api').

Examples

Basic setup with title, description, and version.

NestJS

const config = new DocumentBuilder()
  .setTitle('My App API')
  .setDescription('API for my app')
  .setVersion('0.1')
  .build();

Adds support for Bearer token authentication in the docs.

NestJS

const config = new DocumentBuilder()
  .addBearerAuth()
  .setTitle('Secure API')
  .setVersion('1.0')
  .build();

Serve the Swagger UI at the '/docs' path.

NestJS

SwaggerModule.setup('docs', app, document);

Sample Program

This example creates a NestJS app and sets up Swagger docs at /api. When you run it, you can open the URL to see interactive API docs.

NestJS

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('Cats API')
    .setDescription('API to manage cats')
    .setVersion('1.0')
    .build();

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

  await app.listen(3000);
  console.log('API docs available at http://localhost:3000/api');
}

bootstrap();

Important Notes

Remember to decorate your controllers and DTOs with Swagger decorators like @ApiTags() and @ApiProperty() to improve docs.

Swagger UI is interactive, so you can test API calls directly from the browser.

Keep your API docs updated by running the app after code changes.

Summary

Swagger auto-generates API docs that are easy to read and test.

Use DocumentBuilder to configure your API info.

Serve docs with SwaggerModule.setup() at a chosen URL.

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