การเขียน OpenAPI / Swagger API Specification: นิยาม Endpoint, Request Header, Body และ Response Status Code พร้อมตัวอย่าง

ในยุคของการพัฒนาซอฟต์แวร์แบบ Microservices ระบบต่างๆ จำเป็นต้องสื่อสารกันผ่าน Application Programming Interfaces (APIs) การกำหนดข้อตกลงร่วมกันที่ชัดเจน หรือที่เรียกว่า API Contract จึงเป็นสิ่งสำคัญอย่างยิ่ง หากขาดมาตรฐานนี้ การพัฒนาจะเกิดความคลาดเคลื่อนและปัญหาในการเชื่อมต่อข้อมูล (Integration) อย่างหลีกเลี่ยงไม่ได้

OpenAPI Specification (OAS): หัวใจของการนิยาม API Contract

OpenAPI Specification (OAS) คือมาตรฐานอุตสาหกรรมที่ใช้ในการกำหนดรายละเอียดของ RESTful API อย่างเป็นทางการ การเขียน Spec นี้ช่วยให้เราสามารถนิยามทุกองค์ประกอบของการเรียกใช้งานได้อย่างครบถ้วน ตั้งแต่ Endpoint Path, HTTP Method, รูปแบบของ Request Body, ไปจนถึง Response Status Code และ Schema ของข้อมูลที่คาดว่าจะได้รับกลับมา

ในฐานะ Senior Architect เราต้องมั่นใจว่า Spec ที่เขียนขึ้นนั้นไม่เพียงแต่เป็นเอกสารสำหรับนักพัฒนาเท่านั้น แต่ยังต้องเป็นแหล่งอ้างอิงที่เชื่อถือได้ ซึ่งแหล่งข้อมูลที่แท้จริง (Source of Truth) ของเราคือฐานข้อมูล โดยเฉพาะเมื่อเราใช้ PostgreSQL ซึ่งเป็นระบบที่ให้ความแม่นยำของ Schema สูง

การผสาน OpenAPI กับ PostgreSQL Schema

เมื่อเรากำหนด API Endpoint เช่น การดึงข้อมูลสินค้า (Product List) เราต้องอ้างอิงโครงสร้างข้อมูล (Schema) จาก PostgreSQL เพื่อให้มั่นใจว่า Request Body และ Response Body มีความสอดคล้องกัน การใช้คำสั่ง SQL ในการนิยาม Schema จะเป็นตัวอย่างที่ดีที่สุดในการกำหนดโครงสร้างข้อมูลที่ API ต้องปฏิบัติตาม

ตัวอย่างการนิยาม Schema ของ Endpoint (Product List)

สมมติว่าเรากำลังสร้าง Endpoint GET /api/v1/products เพื่อดึงรายการสินค้า โดยข้อมูลเหล่านี้ถูกเก็บอยู่ในตาราง `products` ของ PostgreSQL

1. การนิยาม Schema (Source of Truth):

SQL

CREATE TABLE products (
    product_id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    category VARCHAR(100) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    is_available BOOLEAN DEFAULT TRUE
);

2. การนิยาม API Parameters และ Response Body:

• Path/Query Parameters: กำหนดตัวกรอง เช่น `?category=electronics`
• Request Body (POST/PUT): กำหนด Schema ของข้อมูลที่ส่งเข้ามา (เช่น ต้องมี `name` เป็น string และ `price` เป็น numeric)
• Response Body (200 OK): ต้องมีโครงสร้างที่ตรงกับคอลัมน์ในตาราง `products`

การจัดการ Status Codes และ Error Handling

การระบุ Status Code ที่สมบูรณ์เป็นสิ่งสำคัญไม่แพ้การนิยาม Schema:

• 200 OK: สำเร็จ, ส่งข้อมูลรายการสินค้ากลับมา
• 400 Bad Request: Client ส่งข้อมูลไม่ถูกต้อง (เช่น ส่ง `price` เป็นตัวอักษรแทนตัวเลข)
• 401 Unauthorized: ผู้ใช้ไม่มีสิทธิ์ในการเข้าถึง
• 500 Internal Server Error: เกิดข้อผิดพลาดที่ฝั่ง Server (เช่น การเชื่อมต่อฐานข้อมูลล้มเหลว)

บทสรุป

การใช้ OpenAPI Specification ร่วมกับการอ้างอิง Schema จาก PostgreSQL อย่างเคร่งครัด ไม่เพียงแต่ทำให้เกิดเอกสาร API ที่สมบูรณ์เท่านั้น แต่ยังช่วยให้ทีมพัฒนาทั้งหมดมี ‘สัญญา’ (Contract) ร่วมกันที่แข็งแกร่ง ทำให้การพัฒนาและการบำรุงรักษาระบบที่ซับซ้อนเป็นไปอย่างราบรื่นและมีประสิทธิภาพสูงสุด