Bạn tạo tài liệu API với Swagger như thế nào?

Question

Accepted Answer

NestJS tích hợp với **Swagger/OpenAPI** qua `@nestjs/swagger` để **tự động sinh tài liệu API tương tác** từ code của bạn — controller, route, DTO, và decorator. Nó tạo ra một UI có thể duyệt nơi các lập trình viên có thể khám phá và test các endpoint, được giữ đồng bộ với code.

## Thiết lập 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()                       // tài liệu hóa JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // phục vụ UI tại /api/docs
```

Với vài dòng, Swagger quét ứng dụng của bạn và phục vụ tài liệu tương tác tại `/api/docs` — tự động phản ánh các route, tham số, và DTO của bạn.

## Tài liệu hóa DTO và response

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

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

@ApiPropertyOptional()                 // trường tùy chọn trong tài liệu
  age?: number;
}
```

Các decorator `@ApiProperty` thêm mô tả, ví dụ, và ràng buộc vào các trường DTO, làm phong phú schema được sinh ra. (Nhiều thứ được suy luận tự động từ các kiểu TypeScript và các decorator `class-validator` — `CLI plugin` có thể giảm cả phần boilerplate này.)

## Tài liệu hóa endpoint

```ts
@ApiTags("users")                        // nhóm các endpoint trong 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) {}
}
```

Các decorator như `@ApiTags`, `@ApiOperation`, và `@ApiResponse` thêm mô tả, nhóm các endpoint, và tài liệu hóa các response có thể có.

## Bạn nhận được gì

```text
✓ UI tương tác (Swagger UI) — duyệt, đọc, và TEST các endpoint trong trình duyệt
✓ Tự động sinh, luôn đồng bộ với code (không có tài liệu riêng để bảo trì)
✓ Spec OpenAPI (JSON) — dùng được để sinh client SDK, cho contract testing, v.v.
✓ Các schema request/response, quy tắc validation, yêu cầu auth đều được tài liệu hóa
```

## Tại sao điều này quan trọng

Tài liệu API là thiết yếu cho bất kỳ API nào được người khác tiêu thụ — các team frontend, ứng dụng mobile, các bên tích hợp thứ ba, hoặc thậm chí chính bạn trong tương lai — và tích hợp Swagger của NestJS làm cho việc tạo tài liệu chất lượng cao trở nên dễ dàng và đáng tin cậy đáng kể.

Lợi thế then chốt là tài liệu được **tự động sinh từ code** (controller, route, DTO, và decorator), nên nó luôn **đồng bộ** với triển khai thực tế thay vì trôi dạt lỗi thời như tài liệu viết tay không thể tránh khỏi.

Hiểu nó là giá trị vì tài liệu API tốt cải thiện đáng kể trải nghiệm lập trình viên và giảm ma sát tích hợp: **Swagger UI** tương tác cho phép các consumer khám phá và *test* các endpoint trực tiếp trong trình duyệt, và **spec OpenAPI** được sinh ra có thể thúc đẩy việc sinh client SDK và contract testing.

Biết cách thiết lập Swagger, làm phong phú tài liệu với các decorator (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), và tài liệu hóa xác thực là kiến thức thực tế, thường cần — các API được tài liệu hóa tốt là một chuẩn chuyên nghiệp và là dấu ấn của công việc back-end chất lượng.

Vì NestJS tận dụng cấu trúc decorator/DTO của nó để sinh nhiều thứ tự động (với nỗ lực thêm tối thiểu), có rất ít lý do để không có tài liệu xuất sắc, khiến đây trở thành một khả năng quan trọng, giá trị cao trong các dự án NestJS thực tế.