ตัวตรวจสอบ OpenAPI JSON

ข้อผิดพลาด JSON ที่พบบ่อยซึ่งทำให้การตรวจล้มเหลว

JSON เข้มงวดกว่า YAML ดังนั้นความล้มเหลวส่วนใหญ่ในไฟล์ที่แก้ด้วยมือมาจากไวยากรณ์ ไม่ใช่จากการออกแบบ API สาเหตุที่พบบ่อยได้แก่ เครื่องหมายจุลภาคท้ายสุดหลังพร็อพเพอร์ตี้สุดท้าย, การใช้เครื่องหมายคำพูดเดี่ยวแทนคู่, คอมเมนต์ (JSON ไม่อนุญาต) หรือการลืมปิดวงเล็บปีกกาหลังอ็อบเจกต์ paths ที่ยาว ไฟล์ที่เสียมักจบด้วยข้อความ “Could not parse as JSON or YAML” หรือมีข้อผิดพลาดของฟิลด์ที่หายไป เพราะไม่มีเนื้อหาที่ใช้ได้ถูกอ่านเข้ามา

หากเห็นเพียงข้อผิดพลาดการแยกวิเคราะห์ ให้หาความผิดพลาดของไวยากรณ์ก่อน การตรวจโครงสร้างจะทำงานเมื่อเอกสารถูกอ่านเป็นอ็อบเจกต์ได้แล้วเท่านั้น

ตัวอย่างการทำงาน

ลองดูเอกสารขนาดเล็กนี้

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

เอกสารนี้แยกวิเคราะห์ได้ และมีฟิลด์ openapi กับอ็อบเจกต์ paths อยู่ครบ แต่รายงานยังคงแสดง:

เนื่องจากมีข้อผิดพลาดหนึ่งรายการ เอกสารนี้จึงไม่ถูกระบุว่าถูกต้อง ให้เพิ่ม "version": "1.0.0" ใน info และเปลี่ยนคีย์เป็น /orders การรันครั้งที่สองจะล้างทั้งสองรายการ

การผ่านการตรวจหมายความว่าอะไร และไม่ได้หมายความว่าอะไร

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

ขั้นตอนการทำงานที่ใช้ได้จริงสำหรับสเปค JSON

เก็บสเปคไว้ในระบบควบคุมเวอร์ชัน และวางที่นี่ก่อนทุก commit ที่แตะ paths เนื่องจากการตรวจทำได้รวดเร็ว จึงเป็นขั้นตอนตรวจความสมบูรณ์หลังการรวมการเปลี่ยนแปลงจากหลายคน ซึ่งเป็นช่วงที่มีแนวโน้มเกิดคีย์ซ้ำหรือวงเล็บที่อยู่ผิดที่มากที่สุด หาก JSON ของคุณถูกสร้างโดยสคริปต์บิลด์ ให้วางผลลัพธ์ที่สร้างแล้วแทนเทมเพลต เพื่อทดสอบสิ่งที่ผู้อ่านจะได้รับจริง เมื่อรายงานไม่มีข้อผิดพลาด คุณก็สามารถแชร์ไฟล์หรือส่งให้เครื่องมือสร้างเอกสารได้อย่างมั่นใจมากขึ้นว่าโครงสร้างระดับบนสุดมั่นคง