OpenAPI Diff: จับ Breaking Change ระหว่างเวอร์ชันสเปก API

API contract ของทุกทีมเปลี่ยนแปลงตลอดเวลา สัปดาห์นี้เพิ่ม endpoint ใหม่ สัปดาห์หน้าปรับ parameter แก้ response schema หรือแย่กว่านั้นคือถอด method ที่ลูกค้ากำลังใช้งานอยู่จริง คำถามสำคัญที่ทีมทุกทีมต้องตอบให้ได้ก่อน release คือ "เวอร์ชันใหม่นี้จะทำให้ consumer ที่ใช้อยู่พังหรือเปล่า?" และการตอบคำถามนี้ด้วยการเปิดไฟล์ JSON สองไฟล์ขนาดหลายพันบรรทัดมาไล่เทียบด้วยตาเปล่า เป็นงานที่ทั้งเสียเวลาและผิดพลาดง่ายมาก

OpenAPI Diff tool เกิดมาเพื่อแก้ปัญหานี้โดยเฉพาะ แค่วางสเปก OpenAPI หรือ Swagger JSON สองไฟล์ลงในหน้าเว็บ ตัว tool จะเดิน paths object ครบทุก HTTP method แล้วสรุปรายงานให้ทันทีว่า endpoint ไหนถูกเพิ่ม ไหนถูกลบ ไหนถูกแก้ไข พร้อม flag breaking change ที่สำคัญ ทั้งหมดนี้คำนวณฝั่ง client ใน browser 100% สเปกของคุณไม่เคยออกจากหน้าเว็บเลยแม้แต่ byte เดียว

บทความนี้จะพาไปดูว่า tool ทำอะไรได้บ้าง อะไรถือเป็น breaking change และจะนำรายงานที่ได้ไปใช้ประโยชน์จริงใน workflow ของทีมได้อย่างไร

ทำไมต้องใช้ OpenAPI Diff Tool?

• จับ breaking change ก่อนส่งมอบ — รู้ทันทีว่า endpoint ไหนหายไปหรือ method ไหนถูกถอด ก่อนที่ consumer จะเจอ error 500 จริงใน production
• ประหยัดเวลาไล่ diff ด้วยมือ — สเปกจริงมักมีสิบถึงร้อย endpoint การเดิน paths object ทั้งหมดด้วย script ใน browser เร็วกว่าการเทียบสายตาหลายเท่า
• ไม่ต้องติดตั้งอะไรเลย — ไม่ต้อง setup CLI, ไม่ต้อง install package, เปิดหน้าเว็บแล้ววาง JSON ได้ทันที
• ความปลอดภัยสูง — คำนวณฝั่ง client ทั้งหมด spec ไม่ออกจากหน้าเว็บ เหมาะกับสเปก internal API ที่ห้ามส่งขึ้น server ภายนอก
• รองรับครบทุก HTTP method — GET, POST, PUT, PATCH, DELETE, HEAD และ OPTIONS ถูกเดินครบ ไม่มี endpoint ตกหล่น
• ใช้เป็น API changelog ได้ทันที — รายงานที่ได้สรุปการเปลี่ยนแปลงชัดเจน นำไปแปะใน release note หรือแชร์ให้ทีม consumer ได้เลย

ฟีเจอร์หลัก

รายละเอียดเพิ่มเติมที่น่าสนใจ:

• รองรับทั้ง OpenAPI (Swagger 2.0 และ OpenAPI 3.x) ที่เป็น JSON จึงใช้กับสเปกเก่า ๆ ในโปรเจกต์ legacy ได้
• ผลลัพธ์จัดกลุ่มตามหมวด added / removed / modified ทำให้อ่านรายงานเร็วและนำไปใช้เป็น changelog ได้ทันที
• เพราะรันใน browser ล้วน จึงใช้งานได้แม้ออฟไลน์ เหมาะกับการรีวิวสเปกในสภาพแวดล้อมที่จำกัดเครือข่าย

วิธีเทียบสเปก API สองเวอร์ชัน

1. เปิด หน้า OpenAPI Diff tool ใน browser ของคุณ
2. วางสเปก OpenAPI หรือ Swagger JSON เวอร์ชันเก่า (base) ลงในช่องแรก
3. วางสเปกเวอร์ชันใหม่ (target) ที่ต้องการเทียบลงในช่องที่สอง
4. รอแป๊บเดียว tool จะเดิน paths object ของทั้งสองไฟล์ครบทุก HTTP method แล้วสรุปผลให้
5. อ่านรายงานใน 3 หมวด คือ endpoint ที่เพิ่ม, endpoint ที่ลบ และ method ที่แก้ไข พร้อมจุดที่ถูก flag เป็น breaking change

ไม่มีขั้นตอนซับซ้อนกว่านี้ ไม่ต้องสมัครสมาชิก ไม่ต้องอัปโหลดไฟล์ และไม่มีข้อมูลใดถูกส่งออกจากเครื่องคุณ

อะไรถือเป็น Breaking Change

หัวใจของการทำ spec diffing คือการแยกแยะว่าการเปลี่ยนแปลงแบบไหนอันตราย และแบบไหนปลอดภัย

การเดิน paths object — tool ไล่ทุก key ใน paths object ของทั้งสองสเปก แล้วต่อด้วยทุก HTTP method ภายใต้แต่ละ path วิธีนี้ทำให้มองเห็น contract ในระดับ "path + method" ซึ่งตรงกับวิธีที่ client จริงเรียกใช้งาน

endpoint และ method ที่ถูกลบ — ถ้า path หายไปจากสเปกใหม่ หรือ path ยังอยู่แต่ method ใดถูกถอดออก (เช่น DELETE หายไป) นั่นคือ breaking change ชัดเจน เพราะทุก client ที่เคยเรียก path+method นั้นจะเจอ 404 หรือ 405 ทันที

response และ parameter ที่แก้ไข — endpoint ที่ยังอยู่แต่รายละเอียดภายในเปลี่ยน เช่น required parameter เพิ่ม, โครงสร้าง response เปลี่ยน หรือ content type ต่างกัน จะถูกรายงานเป็น method ที่ถูกแก้ไข ให้ทีมไปตรวจเชิงลึกต่อว่าผลกระทบเป็นแบบไหน

endpoint ใหม่คือการเปลี่ยนที่ปลอดภัย — การเพิ่ม path+method ใหม่ไม่ทำให้ client เดิมพัง เพราะ client เดิมไม่ได้เรียกมันอยู่แล้ว จึงถือเป็น non-breaking change แต่ก็ควรอยู่ใน changelog เพื่อให้ consumer รู้ว่ามีความสามารถใหม่ให้ใช้

สรุปเป็นตารางเทียบกันได้ว่า:

รายงานที่ได้จาก tool สามารถใช้เป็น API changelog ได้เลย ยกตัวอย่างหน้าตาของรายงาน:

Added:    POST /v2/invoices
Removed:  GET /v1/users/{id}/history   (breaking)
Modified: POST /v1/orders              (breaking)
Total: 3 changes, 2 breaking changes

แค่บรรทัดเดียวที่มีคำว่า breaking ก็เพียงพอทำให้ทีมรู้ว่าต้องหยุด ประเมิน แล้วคุยกับ consumer ก่อน merge

กรณีใช้งานจริง

ประตูรีวิวก่อน release

กำหนดให้ทุก PR ที่แก้ไขไฟล์ openapi.json ต้องผ่านการรัน diff กับสเปกเวอร์ชัน production ก่อน ถ้ามี breaking change ปรากฏขึ้น ทีมต้องตอบให้ได้ว่ามี plan รองรับแล้ว เช่น bump เวอร์ชันเป็น v3, เก็บ endpoint เดิมไว้ชั่วคราว หรือแจ้งล่วงหน้าให้ consumer ปรับตัว แนวทางนี้เปลี่ยน breaking change จากเรื่องที่ค้นพบหลัง release ให้กลายเป็นเรื่องที่ถูกตัดสินใจอย่างมีสติตั้งแต่ตอนรีวิวโค้ด

สร้าง changelog อัตโนมัติ

ทีมที่ release API บ่อยมักตกหล่นเรื่อง release note เพราะจำไม่ได้ว่าแก้อะไรไปบ้าง ด้วยการเทียบสเปกของเวอร์ชันล่าสุดกับเวอร์ชันก่อนหน้า คุณได้รายการ added / removed / modified ที่ตรงกับความจริง 100% นำไปแปะใน CHANGELOG.md หรือส่งเป็น announcement ใน Slack ให้ทีม integration ได้ทันที

contract testing กับ consumer

ทีมที่ดูแล mobile app หรือ frontend ที่เรียก API ของทีมอื่น สามารถรัน diff ระหว่างสเปกที่ตัวเอง develop อยู่กับสเปกล่าสุดของ backend เพื่อดูว่า contract ที่ตัวเองเขียนโค้ดอ้างอิงไว้ยังตรงอยู่ไหม จุดไหนถูกแก้ไขก็ไปอัปเดต test case หรือ client SDK ตรงนั้น ช่วยลดปัญหา integration surprise ช่วงเก็บงาน

audit API จาก vendor

เมื่อ vendor อัปเดตสเปก API มาให้ใช้ อย่าเชื่อว่า "ไม่มีอะไรเปลี่ยน" วางสเปกเก่ากับสเปกใหม่ลงใน tool แล้วดูด้วยตาตัวเองว่า endpoint ไหนหาย ไหนแก้ แบบนี้คุณจะรู้ล่วงหน้าว่าต้องปรับ integration ของตัวเองตรงไหน ก่อนที่ production จะเป็นคนบอก

แนวทางปฏิบัติที่ดี

• ทำ diff เป็นกิจวัตร ไม่ใช่ครั้งคราว — รันทุกครั้งก่อน release หรือผูกเข้ากับช่วง code review ยิ่งเจอเร็วยิ่งแก้ถูก
• เก็บสเปก production ไว้เป็น baseline เสมอ — เทียบกับสเปกที่กำลังจะปล่อย จะได้เห็นความต่างที่ consumer จริงจะเจอ
• อย่าลืมว่าการแก้ไข method บางแบบคือ breaking — required parameter ที่เพิ่มใหม่อาจดูเล็ก แต่ทำให้ request เก่าทั้งหมด invalid ได้
• แจ้ง consumer ล่วงหน้าเมื่อต้อง breaking — ใช้รายงานจาก tool เป็นหลักฐานสื่อสาร ระบุวัน deprecate และแนวทาง migration ชัดเจน
• คัดลอกรายงานเก็บไว้ใน release note — เปลี่ยนผล diff ให้เป็น changelog ถาวรของ API ช่วยทีมใหม่เข้าใจประวัติการเปลี่ยนแปลงได้เร็ว
• ใช้คู่กับการตรวจความถูกต้องของสเปก — ก่อน diff ควรมั่นใจว่าสเปก valid อยู่แล้ว ไม่อย่างนั้นผลเทียบอาจคลาดเคลื่อนจาก parsing ที่ผิด

พร้อมจับ breaking change ตัวแรกหรือยัง?

อย่ารอให้ consumer มาแจ้งว่า API พัง ลองเปิด OpenAPI Diff tool วางสเปกสองเวอร์ชันล่าสุดของคุณลงไป แล้วดูให้ชัดว่า contract ที่คุณคิดว่านิ่งนั้น เปลี่ยนไปแค่ไหนแล้ว — ใช้เวลาไม่ถึงนาที ฟรี และสเปกของคุณไม่เคยออกจาก browser

เครื่องมือที่เกี่ยวข้องที่คุณอาจสนใจ:

• OpenAPI Validator — ตรวจความถูกต้องของสเปกก่อนนำไปเทียบ
• OpenAPI to cURL Converter — แปลง endpoint ในสเปกเป็นคำสั่ง cURL พร้อมทดสอบ
• API Endpoint Tester — ยิง request จริงไปยัง endpoint เพื่อยืนยันพฤติกรรม

ขอให้เทียบสเปกอย่างสนุก!

คำถามที่พบบ่อย

ถ: tool รองรับสเปกแบบไหนบ้าง?

ตอบ: รองรับ OpenAPI และ Swagger ที่เป็นไฟล์ JSON ครอบคลุมทั้ง Swagger 2.0 และ OpenAPI 3.x ที่นิยมใช้กันในโปรเจกต์ส่วนใหญ่

ถ: สเปกของผมถูกส่งขึ้น server ไหม?

ตอบ: ไม่ การประมวลผลทั้งหมดเกิดขึ้นใน browser ฝั่งคุณ 100% สเปกไม่ถูกอัปโหลดหรือบันทึกไว้ที่ใด ปิดแท็บเมื่อไรข้อมูลก็หายไปเมื่อนั้น

ถ: ถ้า endpoint เพิ่มขึ้นถือเป็น breaking change ไหม?

ตอบ: ไม่ถือ เพราะ client เดิมไม่ได้เรียก endpoint ใหม่อยู่แล้ว จึงไม่มีใครพัง แต่การเพิ่ม endpoint ควรถูกบันทึกใน changelog เพื่อให้ consumer รู้ว่ามีความสามารถใหม่

ถ: ใช้กับสเปก YAML ได้หรือเปล่า?

ตอบ: tool ออกแบบมาสำหรับ JSON ถ้าสเปกของคุณเป็น YAML ให้แปลงเป็น JSON ก่อน จากนั้นจึงวางลงใน tool ได้ตามปกติ

ถ: รายงานที่ได้นำไปใช้ต่ออย่างไรได้บ้าง?

ตอบ: ใช้เป็น API changelog ใน release note, ใช้เป็นประเด็นคุยในช่วง code review, ใช้วางแผน contract testing กับทีม consumer และใช้ audit การเปลี่ยนแปลงสเปกที่ได้รับจาก vendor ได้ทั้งหมด