OpenAPI Diff และตัวตรวจสอบ Breaking Change

เปรียบเทียบสเปก OpenAPI หรือ Swagger สองไฟล์ และชี้การเปลี่ยนแปลง API ที่ทำให้ไคลเอนต์พัง

อินพุต

สเปกฐาน

วาง JSON หรือ YAML, อัปโหลดไฟล์ หรือนำเข้าจาก URL

สเปกใหม่

วาง JSON หรือ YAML, อัปโหลดไฟล์ หรือนำเข้าจาก URL

ผลลัพธ์

เปรียบเทียบสเปกสองชุด

เพิ่มสเปกฐานและสเปกใหม่ แล้วเลือกเปรียบเทียบ

รายละเอียด

เลือกการเปลี่ยนแปลงเพื่อดูรายละเอียด

ยังไม่ได้เปรียบเทียบ

Swagger / OpenAPI ตัวแสดงแสดงผลและสำรวจ OpenAPI 3.x และ Swagger 2.0 ได้ทันที HAR เป็น OpenAPIสร้างสัญญา OpenAPI ที่ตรวจสอบได้จากทราฟฟิกเบราว์เซอร์ที่ล้างข้อมูลแล้ว Mini Postman (เครื่องทดสอบ API)ทดสอบ REST API โดยตรงในเบราว์เซอร์ — ไม่ต้องติดตั้ง JSON Diff ตัวตรวจสอบตรวจจับทุกการเปลี่ยนแปลงระหว่าง JSON สองรายการทันที

OpenAPI Diff ตรวจสอบอะไรบ้าง

OpenAPI Diff เปรียบเทียบสเปก API ฐานกับสเปกใหม่ตามความหมาย ไม่ใช่ตามตัวอักษร โดยจับคู่การดำเนินการด้วยเมธอดและ path (ดังนั้น /users/{id} กับ /users/{userId} จึงเป็นเอนด์พอยต์เดียวกัน) แก้การอ้างอิง $ref ภายใน และรายงานทุกการเปลี่ยนแปลงของสัญญาพร้อมการดำเนินการ ตำแหน่ง ค่าก่อนและหลัง และเหตุผลที่สำคัญต่อไคลเอนต์ รองรับ Swagger 2.0, OpenAPI 3.0 และ OpenAPI 3.1 ทั้งแบบ JSON และ YAML โดย Swagger 2.0 จะถูกแปลงเป็นรูปแบบ OpenAPI 3 ก่อน

วิธีใช้งาน

1.วาง อัปโหลด หรือนำเข้าสเปกฐาน (เวอร์ชันที่ไคลเอนต์ใช้อยู่ในปัจจุบัน)
2.เพิ่มสเปกใหม่ (เวอร์ชันที่เสนอ)
3.เลือกเปรียบเทียบ
4.ดูแท็บเข้ากันไม่ได้, คำเตือน และเข้ากันได้ แล้วกรองตามเมธอดหรือส่วน
5.เลือกการเปลี่ยนแปลงเพื่อดูค่าก่อนและหลัง รวมถึงเหตุผลที่สำคัญ
6.คัดลอกการเปลี่ยนแปลงที่เข้ากันไม่ได้ ไปใส่ใน pull request หรือดาวน์โหลดรายงาน Markdown หรือ JSON สำหรับ CI

การจัดประเภทการเปลี่ยนแปลง

รีเควสต์และเรสปอนส์ถูกประเมินในทิศทางตรงข้ามกัน ฝั่งรีเควสต์ (สิ่งที่ไคลเอนต์ส่ง) สิ่งใดที่ทำให้สิ่งที่รับได้แคบลงถือเป็นเข้ากันไม่ได้ ได้แก่ พารามิเตอร์หรือพรอพเพอร์ตีที่จำเป็นใหม่ ค่า enum ที่ถูกลบ ชนิดข้อมูลหรือฟอร์แมตที่เปลี่ยน ค่าสูงสุดที่ลดลงหรือค่าต่ำสุดที่เพิ่มขึ้น แพตเทิร์นใหม่ หรือ content type ที่ถูกลบ ฝั่งเรสปอนส์ (สิ่งที่ไคลเอนต์ได้รับ) สิ่งใดที่ลบหรือขยายสิ่งที่ไคลเอนต์อ่านถือเป็นเข้ากันไม่ได้ หรือคำเตือน ได้แก่ พรอพเพอร์ตีหรือสถานะสำเร็จที่ถูกลบ ชนิดข้อมูลที่เปลี่ยน ค่า enum ใหม่ หรือพรอพเพอร์ตีที่จำเป็นแต่กลายเป็นไม่บังคับ เอนด์พอยต์ที่ถูกลบ การยืนยันตัวตนใหม่ รูปแบบความปลอดภัยที่เปลี่ยน และ OAuth scope ที่เพิ่มขึ้นล้วนเป็นเข้ากันไม่ได้ ส่วนการแก้ไขคำอธิบาย สรุป ชื่อ และตัวอย่างถือเป็นการเปลี่ยนแปลงเอกสาร และจะถูกซ่อนไว้จนกว่าคุณจะเปิดแสดง

ข้อจำกัดและความเป็นส่วนตัว

การเปรียบเทียบทำงานในเบราว์เซอร์ของคุณด้วยเอนจินกฎในตัว สเปกจะไม่ถูกอัปโหลดไปที่ใด การนำเข้าจาก URL จะดึงไฟล์โดยตรงจากเบราว์เซอร์โดยไม่ส่งคุกกี้ ดังนั้นเซิร์ฟเวอร์ที่บล็อกรีเควสต์ข้ามต้นทางต้องใช้วิธีอัปโหลดหรือวางแทน แต่ละสเปกมีขนาดได้สูงสุด 5 MB ไฟล์ $ref ภายนอกจะถูกรายงานแต่ไม่ถูกดึงข้อมูล เซิร์ฟเวอร์ คอลแบ็ก เว็บฮุก ลิงก์ และส่วนขยายของผู้ให้บริการจะไม่ถูกเปรียบเทียบ และกฎเหล่านี้อธิบายผลกระทบที่น่าจะเกิดกับไคลเอนต์ ไม่ได้รับประกัน เซิร์ฟเวอร์แบบเข้มงวดหรือผ่อนปรนอาจทำงานต่างกัน