คุณสร้าง API documentation ด้วย Swagger อย่างไร?

Question

Accepted Answer

NestJS ผสานรวมกับ **Swagger/OpenAPI** ผ่าน `@nestjs/swagger` เพื่อ **สร้าง API documentation แบบโต้ตอบได้โดยอัตโนมัติ** จากโค้ดของคุณ ได้แก่ controller, route, DTO และเดคอเรเตอร์ มันผลิต UI ที่เรียกดูได้ ซึ่ง developer สามารถสำรวจและทดสอบ endpoint ได้ โดยซิงค์กับโค้ดอยู่เสมอ

## การตั้งค่า 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 จะสแกนแอปของคุณและให้บริการ docs แบบโต้ตอบที่ `/api/docs` โดยสะท้อน route, parameter และ DTO ของคุณโดยอัตโนมัติ

## การ document DTO และ response

```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` เพิ่มคำอธิบาย, ตัวอย่าง และข้อจำกัดให้กับ field ของ DTO ทำให้ schema ที่ generate ออกมาสมบูรณ์ขึ้น (ส่วนใหญ่ถูกอนุมานโดยอัตโนมัติจาก type ของ TypeScript และเดคอเรเตอร์ของ `class-validator` และ `CLI plugin` ยังช่วยลด boilerplate นี้ลงได้อีก)

## การ document endpoint

```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` เพิ่มคำอธิบาย, จัดกลุ่ม endpoint และ document response ที่เป็นไปได้

## สิ่งที่คุณได้รับ

```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 documentation จำเป็นสำหรับ API ใดก็ตามที่ถูกใช้โดยผู้อื่น ไม่ว่าจะเป็นทีม frontend, แอปมือถือ, ผู้ integrate จากภายนอก หรือแม้แต่ตัวคุณเองในอนาคต และการผสานรวม Swagger ของ NestJS ทำให้การผลิต docs คุณภาพสูงง่ายและน่าเชื่อถืออย่างน่าทึ่ง

ข้อได้เปรียบสำคัญคือ documentation ถูก **generate จากโค้ดโดยอัตโนมัติ** (controller, route, DTO และเดคอเรเตอร์) ดังนั้นมันจึง **ซิงค์** กับ implementation จริงแทนที่จะล้าสมัยไปเรื่อยๆ อย่างที่ docs ที่เขียนด้วยมือมักจะเป็น

การเข้าใจมันมีค่าเพราะ API docs ที่ดีช่วยปรับปรุง developer experience อย่างมากและลดแรงเสียดทานในการ integrate: **Swagger UI** แบบโต้ตอบให้ผู้ใช้สำรวจและ *ทดสอบ* endpoint ได้โดยตรงในเบราว์เซอร์ และ **OpenAPI spec** ที่ generate ออกมาสามารถขับเคลื่อนการ generate client SDK และ contract testing ได้

การรู้วิธีตั้งค่า Swagger, เสริม docs ด้วยเดคอเรเตอร์ (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) และ document การ authentication เป็นความรู้ที่ใช้บ่อยและเป็นประโยชน์ในเชิงปฏิบัติ API ที่ document ไว้อย่างดีเป็นมาตรฐานมืออาชีพและเป็นเครื่องหมายของงาน back-end คุณภาพ

เพราะ NestJS ใช้ประโยชน์จากโครงสร้าง decorator/DTO ของมันในการ generate สิ่งต่างๆ ได้มากมายโดยอัตโนมัติ (ด้วยความพยายามเพิ่มเติมเพียงเล็กน้อย) จึงแทบไม่มีข้ออ้างที่จะไม่มี docs ที่ยอดเยี่ยม ทำให้นี่เป็นความสามารถที่สำคัญและมีค่าสูงในโปรเจกต์ NestJS จริง