How do you generate API documentation with Swagger?

Question

Accepted Answer

NestJS integrates with **Swagger/OpenAPI** via `@nestjs/swagger` to **auto-generate interactive API documentation** from your code — controllers, routes, DTOs, and decorators. It produces a browsable UI where developers can explore and test endpoints, kept in sync with the code.

## Setting up Swagger

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

With a few lines, Swagger scans your app and serves interactive docs at `/api/docs` — automatically reflecting your routes, parameters, and DTOs.

## Documenting DTOs and responses

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

`@ApiProperty` decorators add descriptions, examples, and constraints to DTO fields, enriching the generated schema. (Much is inferred automatically from TypeScript types and `class-validator` decorators — the `CLI plugin` can reduce even this boilerplate.)

## Documenting endpoints

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

Decorators like `@ApiTags`, `@ApiOperation`, and `@ApiResponse` add descriptions, group endpoints, and document possible responses.

## What you get

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## Why it matters

API documentation is essential for any API consumed by others — frontend teams, mobile apps, third-party integrators, or even your future self — and NestJS's Swagger integration makes producing high-quality docs remarkably easy and reliable.

The key advantage is that documentation is **auto-generated from the code** (controllers, routes, DTOs, and decorators), so it stays **in sync** with the actual implementation rather than drifting out of date like hand-written docs inevitably do.

Understanding it is valuable because good API docs dramatically improve developer experience and reduce integration friction: the interactive **Swagger UI** lets consumers explore and *test* endpoints directly in the browser, and the generated **OpenAPI spec** can drive client SDK generation and contract testing.

Knowing how to set up Swagger, enrich the docs with decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), and document authentication is practical, frequently-needed knowledge — well-documented APIs are a professional standard and a hallmark of quality back-end work.

Because NestJS leverages its decorator/DTO structure to generate so much automatically (with minimal extra effort), there's little excuse not to have excellent docs, making this an important, high-value capability in real NestJS projects.