Swagger API documentation in NestJS - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is Swagger in the context of API development?

Swagger is a tool that helps you describe, design, and document your APIs in a way that is easy to understand and use. It creates interactive API documentation that lets users try out API calls directly from the browser.

beginner

How do you enable Swagger in a NestJS application?

You enable Swagger by installing the @nestjs/swagger package and then setting up the SwaggerModule in your main.ts file. You create a document describing your API and serve it with a route like '/api'.

intermediate

What decorator is used in NestJS to add metadata for Swagger documentation on a controller method?

The @ApiOperation decorator is used to add a summary or description for a controller method in Swagger documentation.

intermediate

Why is it important to use DTOs (Data Transfer Objects) with Swagger in NestJS?

DTOs define the shape of data sent or received by the API. Using DTOs with Swagger helps generate clear and accurate API models so users know what data to send or expect.

advanced

How can you secure your Swagger API documentation in NestJS so only authorized users can access it?

You can protect the Swagger route by applying authentication guards or middleware to the route serving the Swagger UI, ensuring only authorized users can view the API docs.

Which NestJS package do you install to add Swagger support?

A nestjs-swagger-ui

B @nestjs/api-docs

C swagger-ui-express

D @nestjs/swagger

The official package for Swagger support in NestJS is @nestjs/swagger.

What method from SwaggerModule is used to create the API documentation object?

A buildApi()

B generateDoc()

C createDocument()

D initSwagger()

SwaggerModule.createDocument() generates the API documentation object from your app and options.

Which decorator adds a summary description to a controller method in Swagger docs?

A @ApiSummary()

B @ApiOperation()

C @ApiDescription()

D @ApiDoc()

@ApiOperation() adds a summary or description to a controller method for Swagger.

What is the main benefit of using Swagger UI for your API?

A It provides interactive, easy-to-use API documentation

B It encrypts API requests

C It automatically fixes bugs in your API

D It replaces the need for writing code

Swagger UI provides interactive documentation so users can explore and test your API easily.

How do you serve the Swagger UI at a specific route in NestJS?

A Use SwaggerModule.setup() with the route path

B Add a controller method returning HTML

C Configure it in main.ts with app.use()

D Set a global middleware

SwaggerModule.setup() lets you specify the route where Swagger UI is served.

Explain how to set up Swagger API documentation in a NestJS project from scratch.

Think about the steps in main.ts and how decorators add info.

Describe why using DTOs is helpful when generating Swagger documentation in NestJS.

Consider how data structure helps explain the 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