مدقق OpenAPI بصيغة JSON

أخطاء JSON الشائعة وراء فشل الفحص

صيغة JSON أشد صرامة من YAML، لذلك تأتي معظم حالات الفشل في الملفات المعدّلة يدويًا من الصياغة لا من تصميم الواجهة. الأسباب المعتادة هي فاصلة زائدة بعد آخر خاصية، أو علامات اقتباس مفردة بدل المزدوجة، أو تعليق (لا تسمح 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

احفظ المواصفة في نظام التحكم بالإصدارات، والصقها هنا قبل كل التزام يمسّ paths. ولأن الفحص سريع، فهو يصلح خطوة للتأكد بعد دمج تغييرات من عدة أشخاص، حين تكون المفاتيح المكررة أو القوس في غير موضعه أكثر احتمالًا. إذا كان JSON الخاص بك يولَّد من سكربت بناء، فالصق المخرجات المولَّدة لا القالب، حتى تختبر ما سيستقبله القراء فعلًا. وعندما يكون التقرير نظيفًا، يمكنك مشاركة الملف أو تسليمه لأداة توليد التوثيق بثقة أكبر في سلامة البنية على المستوى الأعلى.