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.

This API already wires Swagger 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 →

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 (main.ts)

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.

Swagger / OpenAPI — reading /docs

After this you can

What produces the /docs page

Swagger setup (main.ts)

Reading /docs like a contract, not just a form

Reading a route’s auth requirement

Keep in mind

Check your understanding