مدقق OpenAPI 3.1

ما الذي تفعله هذه الأداة مع ملفات 3.1

يواءم الإصدار 3.1 المخططات مع JSON Schema 2020-12. لا يقرأ هذا المدقق داخل المخططات إطلاقًا، بل يفحص المستوى الأعلى وإدخالات المسارات فقط. لذلك لا تنجح ميزات مخطط 3.1 مثل مصفوفات الأنواع أو const ولا تفشل هنا. كما لا يتحقق من قيمة الحقل openapi نفسها، فأي حقل openapi يُعد موجودًا.

نمطان في 3.1 يجب الانتباه إليهما

يتيح OpenAPI 3.1 وصف webhooks فقط مع ترك paths خارج المستند. تتطلب هذه الأداة وجود paths، لذلك يُبلَّغ عن مثل هذا الملف بخطأ، مع أن المواصفة تسمح به. إضافة كائن paths: {} فارغ تجتاز الفحص.

قائمة الطرق المستخدمة هنا هي get وpost وput وpatch وdelete وhead وoptions، بالإضافة إلى parameters وsummary وdescription وservers. طريقة trace موجودة في المواصفة لكنها غير مدرجة في هذه القائمة، لذلك تُطلق تحذيرًا يمكنك تجاهله إن كان مقصودًا. التحذيرات لا تجعل المستند غير صالح.

مثال عملي

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

النتيجة: خطأ واحد، هو “Missing ‘paths’ object.”. أضف paths: {} فتجتاز البنية الفحص.

متى تستخدم هذه الأداة ومتى تذهب أبعد

استخدم هذه الصفحة للتأكد من أن ملف 3.1 مُهيكل بشكل صحيح قبل فتح طلب دمج أو مشاركته مع شريك. الفحوص سريعة والرسائل واضحة. بعد أن تصبح البنية سليمة، ما تزال قواعد مخطط 3.1 تحتاج إلى مدقق شامل، لأن معظم الأخطاء الحقيقية تكمن هناك: إعلانات أنواع غير صحيحة، ومراجع مكسورة، وتعريفات استجابات مفقودة. اعتبر الخطوتين مكملتين لا بديلتين.

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