مدقّق عقود API

تعمل في المتصفح التحقق

الصق مواصفة OpenAPI وتفاعلاً نموذجياً (عنوان URL للطلب وطريقته وجسمه، وحالة الاستجابة وجسمها) للتحقق من الاتجاهين معاً مقابل العقد مع عرض مفصّل للمخالفات.

الخصوصية: تعمل هذه الأداة بالكامل في متصفحك. لا تغادر بياناتك جهازك أبداً.

كيفية استخدام مدقّق عقود API

  1. الصق مستند OpenAPI أو Swagger.
  2. أدخل الطلب: الطريقة، وعنوان URL أو المسار (بما في ذلك سلسلة الاستعلام)، والترويسات والجسم اختيارياً.
  3. أدخل حالة الاستجابة، وترويساتها وجسمها اختيارياً.
  4. انقر «تحقق» (Validate) وراجع جدول الفحوصات — لكل صف بحالة FAIL مخالفات مقابلة أدناه.
  5. أصلح الطلب أو العقد، ثم أعد التشغيل حتى يتطابق الاتجاهان كلاهما.

مزايا مدقّق عقود API

  • عقود OpenAPI 3.0/3.1 وSwagger 2.0 بصيغة YAML أو JSON مع حلّ مراجع $ref المحلية
  • مطابقة قوالب المسارات مع المعاملات وإزالة المسار الأساسي للخادم تلقائياً
  • فحوصات الطلب: الطريقة، ومعاملات المسار والاستعلام والترويسات وملفات تعريف الارتباط المطلوبة، وأنواع المعاملات وقيم enum، وContent-Type المقبول، ومخطط الجسم
  • فحوصات الاستجابة: الحالة الموثّقة (بما فيها الأنماط الشاملة مثل 2XX والاستجابة default)، والترويسات المصرَّح بها، وContent-Type، ومخطط الجسم
  • جدول مخالفات يعرض الاتجاه والموضع والرسالة؛ مع صفوف تحذيرات ومعلومات للأخطاء المحتملة
  • يستخدم محرّك JSON Schema نفسه المستخدم في مدقّق JSON Schema (الصيغ وnullable والتركيب)

مثال على مدقّق عقود API

إنشاء طلبية بعنصر غير صالح واستجابة غير صالحة

الإدخال:

POST https://api.example.com/v1/orders
X-Request-Id: not-a-uuid
{ "customerId": "cus_8f2a", "items": [{ "sku": "SKU-1", "qty": 0 }] }

201 → { "id": "42", "status": "confirmed", "total": 59.9, "createdAt": "2026-09-01T10:00:00Z" }

النتيجة:

Conforms: No — 5 violations (2 request, 3 response)
request · header.X-Request-Id: Parameter "header.X-Request-Id": String is not a valid uuid.
request · body $.items[0].qty: Value must be ≥ 1. (minimum)
response · header.Location: Required response header "Location" is missing.
response · body $.id: Expected integer but got string. (type)
response · body $.status: Value must be one of: "pending", "paid", "shipped". (enum)

الأسئلة الشائعة حول مدقّق عقود API

ما إصدارات المواصفة المدعومة؟

OpenAPI 3.0 و3.1 وSwagger 2.0، بصيغة YAML أو JSON، مع حلّ مراجع $ref المحلية للمعاملات وأجسام الطلبات والاستجابات والمخططات.

كيف تُطابَق المسارات؟

يُطابَق عنوان URL للطلب (أو المسار) مع قوالب المسارات، مع تفضيل المقاطع الحرفية على المعاملات؛ وتُزال المسارات الأساسية للخادم (servers[].url أو basePath) تلقائياً.

ما الذي يُتحقق منه في جانب الطلب؟

وجود الطريقة، ومعاملات المسار والاستعلام والترويسات وملفات تعريف الارتباط المطلوبة مع فحص النوع والقيود، وContent-Type المقبول، وجسم الطلب مقابل مخططه.

ما الذي يُتحقق منه في جانب الاستجابة؟

أن الحالة موثّقة (بما في ذلك الأنماط الشاملة مثل 2XX والاستجابة default)، وترويسات الاستجابة المصرَّح بها، وContent-Type الخاص بالاستجابة، والجسم مقابل مخطط تلك الحالة.

ماذا تعني صفوف التحذيرات والمعلومات؟

صفوف «المخالفة» (Violation) وحدها هي التي تُخلّ بالمطابقة. ترصد التحذيرات الأخطاء المحتملة (جسم غير موثّق، أو غياب Content-Type)؛ وتشير صفوف المعلومات إلى الإضافات مثل معاملات الاستعلام غير المصرَّح بها.

ملاحظات تقنية

تصل قيم الاستعلام والمسار والترويسات على هيئة سلاسل نصية، لذا يحوّلها المدقّق إلى النوع الأولي المصرَّح به (integer أو number أو boolean أو array عبر صيغ التجميع بالفاصلة أو الشريط العمودي أو المسافة) قبل تشغيل فحص المخطط. وتُحلَّل الكائنات في معاملات الاستعلام بوصفها JSON.

تُطابَق أنواع المحتوى مطابقة تامة أولاً، ثم بالأحرف البديلة (application/* و*/*)، ثم بعائلة اللاحقة المهيكلة (structured suffix)، بحيث يفي application/problem+json بعقد يوثّق application/json. ويعمل التحقق من المخطط باعتبار المستند بأكمله جذراً لمراجع $ref، فتُحلّ مراجع #/components/schemas و#/definitions دون نسخ.