Topic

Swagger / OpenAPI — reading /docs

Definition

OpenAPI is a machine-readable specification of an HTTP API’s routes, parameters, and schemas, and Swagger is the tooling — including an interactive UI — that Nest’s @nestjs/swagger module generates from decorators already present on controllers and DTOs.

In simpler words

Swagger reads the same decorators you already wrote for routing and validation, and turns them into a browsable, testable API reference at /docs.

In a Nest API, Swagger is typically wired up in main.ts. Treat this topic as conceptual: understand what generates the document and how to read it, rather than configuring it from scratch.

Open official example (opens in new tab)

After this you can

Explain what generates the /docs page
Match a DTO’s decorators to its Swagger schema
Use /docs to confirm a route’s auth requirement

What produces the /docs page

Definition

SwaggerModule.createDocument builds an OpenAPI document from a DocumentBuilder configuration plus the ApiTags, ApiCookieAuth, ApiProperty, and similar decorators already present on controllers and DTOs, and SwaggerModule.setup serves an interactive UI for that document at a chosen path.

In simpler words

You are not writing separate documentation — you are letting Nest read the same decorators that already do routing and validation.

main.ts configures the title, description, version, and addCookieAuth("access_token"), then serves the result at /docs.

ApiProperty / ApiPropertyOptional on DTO fields is what makes CreateTicketDto’s shape visible in the generated schema — an undecorated field can still validate but will not show accurately in Swagger.

Swagger setup

const swagger = new DocumentBuilder()
  .setTitle('API')
  .setVersion('0.1.0')
  .addCookieAuth('access_token')
  .build();
SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, swagger));

addCookieAuth registers the same cookie scheme the controllers reference with @ApiCookieAuth.

Reading /docs like a contract, not just a form

Definition

The generated document is the same contract AllExceptionsFilter and each DTO already enforce, so reading it is a fast way to confirm required fields, enums, and auth requirements without opening source files.

In simpler words

Swagger’s Authorize button and its Try it out panel exercise the real endpoints — a 401 there means the same thing a 401 means from curl.

@ApiCookieAuth marks which controllers expect the cookie session, matching the scheme name registered by addCookieAuth.

Because JwtStrategy also accepts a bearer Authorization header, Swagger’s Authorize dialog can supply a raw token for testing without a browser cookie.

Reading a route’s auth requirement

@ApiTags('tickets')
@ApiCookieAuth('access_token')
@Controller('tickets')
export class TicketsController { /* ... */ }

Every route in this controller expects the access_token cookie scheme shown in /docs; role restrictions like @Roles still live in the code, not in this class-level decorator.

Keep in mind

Treat Swagger as generated, not authored — fix the DTO/decorator, not the JSON it produces.
Use /docs to sanity-check a contract before writing a curl command by hand.
Keep API descriptions current when a route’s behavior changes.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. How is /docs generated?

Concept

From a hand-written YAML kept forever separate from DTOsOnce at npm install and never updatedSwaggerModule from DocumentBuilder plus code decorators like ApiTags/ApiCookieAuth/ApiPropertyBy Next.js only

2. Does ApiProperty change ValidationPipe behavior?

Syntax

Yes — @ApiProperty({ required: true }) makes the field requiredYes — its type option is enforced at runtimeYes — @ApiProperty and @IsString are aliasesNo — documentation ≠ class-validator rules

3. Why decorate DTOs for Swagger?

Practical

So ValidationPipe knows which fields to enforceSo TypeORM infers the entity columns from the DTOSo the documented fields become required in the requestSo /docs shows field types/examples matching the contract

4. What does ApiCookieAuth communicate?

Logic

That the route enforces cookie auth at runtime, replacing the guardThat Swagger will attach the auth cookie automatically for youThat the cookie is signed by DocumentBuilder before sendingThat routes expect cookie-based auth in the documented security scheme

5. Does /docs update when you add routes?

Concept

No — you must regenerate the YAML and redeployOnly after running a swagger:build scriptOnly routes decorated with @ApiOperation appearYes — it reflects the running app’s decorated controllers

6. Is a separate OpenAPI YAML required?

Practical

Yes — SwaggerModule reads from a required openapi.yaml fileYes — the decorators only work if a YAML seed existsYes — DocumentBuilder loads a YAML from disk at bootNo — Nest can generate from decorators (YAML optional if you choose)

7. What should stay accurate in Swagger?

Syntax

Auth requirements, DTO shapes, and status responsesOnly the endpoint paths, not their request or response bodiesOnly the response examples, since types are inferredOnly the auth scheme; DTO shapes are documented elsewhere

8. Can Swagger Try it out replace Postman learning?

Logic

Yes — Try it out authenticates you automaticallyIt helps, but cookie/auth setup still must be correct to succeedYes — it sends requests server-side, so guards are skippedYes — it injects a valid JWT into every request

9. What is DocumentBuilder for?

Concept

Scanning controllers to build the route list automaticallyGenerating DTO classes from the OpenAPI specConfiguring OpenAPI title/description/security for SwaggerModuleRegistering the /docs route on the Express app

10. Why tag controllers with ApiTags?

Practical

Set the controller’s route prefixRestrict the endpoints to a named roleGroup endpoints in /docs UIVersion the endpoints under a tag path

11. Does adding @ApiProperty validate the title at runtime?

Conceptintermediate

export class CreateTicketDto {
  @ApiProperty({ example: 'Login bug' })
  title: string;
}

No — @ApiProperty only documents OpenAPI; add @IsString to validateYes — @ApiProperty enforces the typeYes — example values are validatedOnly when whitelist is enabled

12. What does addCookieAuth do in the generated docs?

Syntaxintermediate

const config = new DocumentBuilder()
  .setTitle('Tickets API')
  .addCookieAuth('access_token')
  .build();

Declares a cookie security scheme so /docs shows routes need the auth cookieSigns a real JWT for testingForces every route to be publicValidates cookies at runtime

13. What contract problem does this create?

Practicaladvanced

@Get()
@ApiOkResponse({ type: TicketDto })
list(): TicketWithSecretDto[] { /* ... */ }

@ApiOkResponse changes the runtime return typeNest refuses to compile mismatched typesThe documented response type does not match what the handler actually returnsThe client will receive TicketDto regardless

14. What does @ApiTags affect here?

Logicintermediate

@ApiTags('tickets')
@Controller('tickets')
export class TicketsController {}

It sets the route prefix to ticketsIt groups these endpoints under a "tickets" section in the /docs UIIt creates a Postgres schema named ticketsIt restricts access to the tickets role

15. Why does Try it out fail on this protected route?

Conceptadvanced

// Swagger "Try it out" on DELETE /tickets/:id returns 401

Swagger cannot send DELETE requestsThe browser request lacks the auth cookie the guard requiresThe route is missing @ApiOperationDocumentBuilder disabled the route

Checking your session…