Swagger API documentation in NestJS - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

What is the output of this Swagger setup in NestJS?

Given this NestJS Swagger setup, what will the generated API documentation show for the GET /cats endpoint?

NestJS

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

@ApiTags('cats')
@Controller('cats')
export class CatsController {
  @Get()
  @ApiOperation({ summary: 'List all cats' })
  findAll() {
    return ['Tom', 'Garfield'];
  }
}

A The Swagger UI will show a 'cats' section with a GET /cats endpoint labeled 'List all cats'.

B The Swagger UI will show no endpoints because @ApiTags is missing.

C The Swagger UI will show a POST /cats endpoint instead of GET.

D The Swagger UI will show the GET /cats endpoint but with no description.

💡 Hint

Look at the decorators @ApiTags and @ApiOperation and what they do.

The @ApiTags('cats') decorator groups the controller endpoints under the 'cats' tag in Swagger UI. The @ApiOperation decorator adds a summary description to the GET /cats endpoint. So the Swagger UI will show a 'cats' section with the GET /cats endpoint labeled 'List all cats'.

📝 Syntax

intermediate

Which option correctly adds a query parameter to Swagger docs in NestJS?

You want to document a query parameter 'limit' of type number for a GET endpoint using Swagger decorators in NestJS. Which option correctly adds this parameter?

NestJS

import { Controller, Get, Query } from '@nestjs/common';
import { ApiQuery } from '@nestjs/swagger';

@Controller('items')
export class ItemsController {
  @Get()
  // Add query param decorator here
  findAll(@Query('limit') limit: number) {
    return [];
  }
}

A @ApiQuery('limit')

B @ApiQuery({ name: 'limit', type: 'string', required: true })

C @ApiQuery({ name: 'limit', type: Number, required: false })

D @ApiParam({ name: 'limit', type: Number })

💡 Hint

Check the correct decorator for query parameters and the type property.

The @ApiQuery decorator documents query parameters. The type should be Number (the class, not string). Option C correctly uses @ApiQuery({ name: 'limit', type: Number, required: false }). Option C uses wrong type and required true. Option C is invalid syntax. Option C uses @ApiParam which is for path parameters, not query.

🔧 Debug

advanced

Why does this Swagger setup not show the expected response schema?

This NestJS controller method uses @ApiResponse but Swagger UI does not show the response schema. What is the cause?

NestJS

import { Controller, Get } from '@nestjs/common';
import { ApiResponse, ApiProperty } from '@nestjs/swagger';

class Cat {
  @ApiProperty()
  name: string;

  @ApiProperty()
  age: number;
}

@Controller('cats')
export class CatsController {
  @Get()
  @ApiResponse({ status: 200, description: 'Success', type: Cat })
  findAll() {
    return [{ name: 'Tom', age: 5 }];
  }
}

A The Cat class lacks decorators like @ApiProperty, so Swagger cannot generate schema.

B The return type must be an array of Cat, but type: Cat is used.

C The controller method must be async to show response schema.

D The @ApiResponse decorator is used incorrectly; it should be @ApiOkResponse.

💡 Hint

Swagger needs metadata on class properties to generate schemas.

Swagger uses decorators like @ApiProperty on class properties to generate response schemas. Without these, the schema is missing. Option A is incorrect because @ApiResponse can be used with type. Option A is irrelevant. Option A is not mandatory; Swagger can infer arrays but needs property metadata.

🧠 Conceptual

advanced

What is the purpose of the SwaggerModule in NestJS?

In NestJS, what does the SwaggerModule do when setting up API documentation?

A It automatically generates API controllers without writing code.

B It creates and serves the Swagger UI and JSON docs based on decorators in the code.

C It replaces the NestJS routing system with Swagger routes.

D It validates incoming API requests against Swagger specs at runtime.

💡 Hint

Think about how SwaggerModule interacts with your NestJS app and decorators.

The SwaggerModule reads the decorators in your NestJS code and generates the Swagger JSON and UI to document your API. It does not generate controllers, replace routing, or validate requests at runtime.

❓ state_output

expert

What is the output of this NestJS Swagger setup with multiple tags and global prefix?

Consider this NestJS app setup with Swagger and a global prefix. What URL will serve the Swagger UI?

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);
  app.setGlobalPrefix('api/v1');

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .addTag('users')
    .addTag('products')
    .build();

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

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

A Swagger UI will not be available because of the global prefix

B Swagger UI will be available at http://localhost:3000/api/v1/docs

C Swagger UI will be available at http://localhost:3000/api/v1/swagger

D Swagger UI will be available at http://localhost:3000/docs

💡 Hint

Check how SwaggerModule.setup path relates to global prefix.

The global prefix applies to the app routes, but SwaggerModule.setup serves the UI at the exact path given relative to the root. So Swagger UI is at /docs, not under the global prefix /api/v1.

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