Postman & Swagger: สื่อสารกับทีมให้เป็นมืออาชีพ

🛑 1. The Problem First: "API ที่ไม่มีใครรู้วิธีใช้"

ลองนึกภาพว่าคุณเป็น Frontend ที่ต้องเชื่อมต่อกับ API ที่ Backend พึ่งเขียนเสร็จ:

// ❌ สถานการณ์: ไม่มี Documentation
fetch("https://api.example.com/v1/update-data", {
  method: "POST",
  body: JSON.stringify({ name: "John" }),
});
// 🌋 พัง! ผลลัพธ์คือ Error 400 เสมอ เพราะคุณไม่รู้ว่าต้องส่ง Header 'X-API-KEY'
// หรือต้องส่งข้อมูลในรูปแบบไหน (id? user_id? uuid?) สุดท้ายคุณต้องทักไปถาม Backend ทุกๆ 5 นาที

ปัญหา: การไม่มี Documentation คือการสร้าง "กำแพง" ระหว่างทีม Backend ต้องคอยตอบคำถามเดิมๆ ซ้ำแล้วซ้ำเล่า ส่วน Frontend ก็ต้องมานั่งเดาใจ (Trial and Error) ทำให้เสียเวลาไปฟรีๆ หลายชั่วโมงต่อวันครับ

💡 2. Real-Life Analogy: คู่มือประกอบเลโก้ vs เครื่องใช้ไฟฟ้าไร้ฉลาก

• Swagger (API Specification): เหมือน "คู่มือการต่อเลโก้". มันบอกชัดเจนว่าชิ้นส่วนไหน (Endpoint) ต้องใช้คู่กับชิ้นไหน มีสีอะไร (Data Type) และถ้าต่อเสร็จหน้าตาจะเป็นยังไง (Sample Response)
• Postman Environments: เหมือน "พวงกุญแจรถยนต์". คุณมีกุญแจทรงเดียวกัน (Collection) แต่สามารถสลับไปไขรถคันที่จอดในสนามซ้อม (Development) หรือรถคันที่วิ่งบนถนนจริง (Production) ได้เพียงแค่เปลี่ยนปุ่มกด ไม่ต้องเดินไปหน้าเครื่องเพื่อแก้ชื่อโฮสต์ด้วยมือ

🚀 3. Execution Journey: ขั้นตอนการสร้าง API Contract

Senior จะสร้าง "สัญญา" (Contract) ให้ทีมเห็นภาพตรงกันก่อนเขียนโค้ด

🛠 Step-by-step:

1. The Contract (Swagger): ติดตั้ง Swagger Middleware ในแอป เพื่อให้ทุุกรหัสโค้ดที่เขียน มี Document งอกออกมาโดยอัตโนมัติ
2. The Playground: เปิดหน้า Swagger UI เพื่อให้ทีมทดลองกด "Try it out" ยิงเล่นได้ทันทีโดยไม่ต้องเขียนโค้ด Frontend
3. The Workflow (Postman): สร้าง Collection รวบรวม Request ทั้งหมด และใช้ {{base_url}} เป็นตัวแปรเพื่อสลับ Environment (Local, Staging, Prod)

// ✅ Best Practice: การระบุรายละเอียด API ใน NestJS (Swagger)
@ApiOperation({ summary: 'สร้างผู้ใช้งานใหม่' })
@ApiResponse({ status: 201, description: 'สร้างสำเร็จ' })
@Post()
async create(@Body() dto: CreateUserDto) { ... }

🪤 4. The Junior Trap: โรค "Hardcode URL ใน Postman"

จูเนียร์มักจะส่ง Export ไฟล์ Postman ที่ข้างในเป็น URL ตรงๆ:

// ❌ Junior Trap: Hardcoded URL
"url": "http://localhost:3000/api/users"
// 🌋 พัง! เมื่อเพื่อนรับไฟล์ไป เขาต้องมานั่งไล่แก้ 'localhost:3000'
// เป็น 'localhost:5000' หรือ URL อื่นๆ ทุกบรรทัดด้วยตัวเอง

ระวัง: การ Hardcode ทุกอย่างคือการสร้างงานให้เพื่อนร่วมทีม ✅ การแก้ไข: ใช้ Environment Variables ใน Postman เสมอ! และส่งไฟล์ Environment ไปพร้อมกับ Collection เพื่อให้เพื่อนสลับโหมดได้ในคลิกเดียว

⚖️ 5. The Why Matrix: Swagger vs Postman

🎓 6. Senior Mindset Summary

การเป็น Senior คือการมองว่า "เราไม่ได้เขียนโปรแกรมให้คอมพิวเตอร์อ่าน แต่เรากำลังสร้างระบบงานให้คนทำงานร่วมกันได้". การลงทุนเวลาเพียงเล็กน้อยเพื่อทำ Documentation ที่ดี จะช่วยประหยัดเวลาทั้งทีมได้มหาศาลครับ!