如何使用 Swagger 生成 API 文档？

Question

Accepted Answer

NestJS 通过 `@nestjs/swagger` 与 **Swagger/OpenAPI** 集成，**从代码中自动生成交互式 API 文档** — 从 controllers、routes、DTOs 和 decorators。它生成一个可浏览的 UI，开发人员可以在其中探索和测试端点，与代码保持同步。

## 设置 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
```

只需几行代码，Swagger 扫描你的应用并在 `/api/docs` 提供交互式文档 — 自动反映你的 routes、parameters 和 DTOs。

## 文档化 DTOs 和响应

```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 为 DTO 字段添加描述、示例和约束，充实生成的 schema。（许多内容从 TypeScript 类型和 `class-validator` decorators 自动推断 — `CLI plugin` 可以进一步减少样板代码。）

## 文档化端点

```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) {}
}
```

`@ApiTags`、`@ApiOperation` 和 `@ApiResponse` 等 decorators 添加描述、分组端点并文档化可能的响应。

## 你获得了什么

```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
```

## 为什么这很重要

API 文档对任何被他人消费的 API 都至关重要 — 前端团队、移动应用、第三方集成者，甚至你未来的自己 — NestJS 的 Swagger 集成使生成高质量文档变得非常简单可靠。

关键优势是文档**从代码自动生成**（controllers、routes、DTOs 和 decorators），因此它**与实际实现保持同步**，而不是像手写文档那样不可避免地过时。

理解它很有价值，因为优秀的 API 文档极大地改善开发者体验并减少集成摩擦：交互式 **Swagger UI** 让使用者直接在浏览器中探索和*测试*端点，生成的 **OpenAPI spec** 可以驱动客户端 SDK 生成和契约测试。

了解如何设置 Swagger、用 decorators 丰富文档（`@ApiProperty`、`@ApiTags`、`@ApiOperation`、`@ApiResponse`）、以及文档化身份验证是实用的、频繁需要的知识 — 文档完善的 API 是专业标准和高质量后端工作的标志。

由于 NestJS 利用其 decorator/DTO 结构自动生成许多内容（只需最少的额外努力），没有理由不拥有优秀的文档，使这成为实际 NestJS 项目中重要的、高价值的能力。