مدقّق OpenAPI — التحقق من مواصفات OpenAPI 3 وSwagger

ما هو اختبار عقود API؟

عقد API هو الوصف المتفق عليه للواجهة — نقاط النهاية والمعاملات ومخططات الطلب والاستجابة ورموز الحالة — ويُكتب عادةً كمستند OpenAPI. اختبار العقد يقارن ما تعيده الخدمة فعلياً بذلك الوصف، فيُكشف الحقل المعاد تسميته أو النوع المتغيّر لدى المنتِج أو المستهلك قبل أن يعطّل الطرف الآخر.

اقرأ الدليل: ما هو اختبار API؟ وكيف تختبر REST API

كيفية استخدام مدقّق OpenAPI

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

مزايا مدقّق OpenAPI

OpenAPI 3.0 و3.1 وSwagger 2.0 بصيغة JSON أو YAML مع أخطاء تحليل دقيقة برقم السطر
الحقول المطلوبة، وصياغة servers/host، وقوالب المسارات مقابل معاملات المسار، ومواقع المعاملات، ومتون الطلبات، والاستجابات
معرّفات العمليات المكرّرة، ومؤشرات $ref المحلية غير المحلولة، والمكوّنات غير المستخدمة، ومخططات الأمان غير المعرّفة، والوسوم غير المستخدمة أو غير المعلنة
فحوصات المخططات: الأنواع غير المعروفة، والمصفوفات دون items، وترتيب min/max، والخصائص المطلوبة غير الموجودة، وnullable في 3.0 مقابل مصفوفات الأنواع في 3.1
المشكلات مرتّبة حسب الخطورة مع مواقعها بصيغة JSON Pointer
إحصاءات المستند: المسارات والعمليات والمعاملات والاستجابات والمخططات ومخططات الأمان والوسوم والخوادم

مثال على مدقّق OpenAPI

اكتشاف معامل مسار معطوب (مقتطف من النتيجة)

الإدخال:

paths:
  /orders/{orderId}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "404": { description: Not found }

النتيجة:

error  #/paths/~1orders~1{orderId}/get/parameters/0/name  Path parameter "id" does not appear in the path template "/orders/{orderId}".
error  #/paths/~1orders~1{orderId}/get/parameters  Path template uses {orderId} but no path parameter "orderId" is defined.
warning  …/responses  No 2xx or default response is documented.

كل موقع في جدول المشكلات مؤشر JSON Pointer: اتبعه مقطعاً مقطعاً من الجذر، واقرأ كل ~1 على أنه /، لتصل إلى السطر الذي فيه الخطأ.

الموقع (JSON Pointer)

الجزء 1:1#/الجزء 2:2paths/الجزء 3:3~1orders~1{orderId}/الجزء 4:4get/الجزء 5:5parameters/الجزء 6:60/الجزء 7:7name

موضعه في YAML

الجزء 2:2paths:
  الجزء 3:3/orders/{orderId}:
    الجزء 4:4get:
      الجزء 5:5parameters:
        الجزء 6:6- الجزء 7:7name: id
          in: path
          …

1جذر المستند
2الكائن paths
3المسار /orders/{orderId}تُكتب الشرطة المائلة / داخل المفتاح على صورة ~1 (RFC 6901) حتى لا تُقرأ فاصلاً
4العملية
5قائمة معاملاتها
6العنصر الأولمواضع المصفوفة تبدأ من 0
7الحقل الذي فيه المشكلةPath parameter "id" does not appear in the path template "/orders/{orderId}".فشل

أول موقع في مخرجات المثال أعلاه؛ والأداة تعرض المؤشر نفسه.

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

ما الذي يجري التحقق منه؟

الحقول المطلوبة في المستوى الأعلى (openapi/swagger وinfo.title وinfo.version وpaths)، وصياغة server وhost، وقوالب المسارات مقابل معاملات المسار، ومواقع المعاملات وأعلام required، ومتون الطلبات، والاستجابات مع أوصافها ورموز الحالة الصالحة، ومعرّفات العمليات المكرّرة، ومؤشرات $ref المحلية غير المحلولة، والمكوّنات غير المستخدمة، ومتطلبات الأمان التي تشير إلى مخططات غير معرّفة، واتساق الوسوم، وسلامة الكلمات المفتاحية في المخططات (items في المصفوفات، وترتيب min/max، وقابلية null في 3.0 مقابل 3.1).

ما الفرق بين الأخطاء والتحذيرات والتلميحات؟

الأخطاء تخالف المواصفة وستعطّل مولّدات الكود أو البوابات. والتحذيرات مسموح بها لكنها خطرة أو غير مفيدة (غياب operationId، أو عدم وجود استجابة 2xx، أو مخطط غير مستخدم). أما التلميحات فاقتراحات لتحسين جودة التوثيق.

هل يتحقق من الأمثلة مقابل المخططات؟

لا. التحقق بنيوي فقط. استخدم أداة مدقّق JSON Schema للتحقق من حمولات الأمثلة مقابل مخطط بعينه.

هل تُجلب ملفات $ref الخارجية؟

لا. يُبلَّغ عن المراجع إلى ملفات أو عناوين URL أخرى بوصفها تلميحات يتعذّر التحقق منها؛ ويُتحقق من كل ما عداها دون اتصال داخل متصفحك.

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

المواقع مؤشرات JSON Pointer (RFC 6901) مع تهريب الشرطات المائلة بـ ~1 بحيث يمكن استخدامها مباشرة مع الأدوات الأخرى. والمدقّق بنيوي وسريع عمداً (تمريرة واحدة دون اتصال بالشبكة)، ما يجعله مناسباً للتحقق الحي أثناء التحرير.

المراجع

OpenAPI SpecificationOpenAPI Initiativeالمعيار لوصف واجهات REST: المسارات والعمليات والمعاملات والمخططات والاستجابات وأنظمة الأمان.
JSON Schema SpecificationJSON Schemaالمفردات المستخدمة لوصف بنية مستندات JSON والتحقق منها (الأنواع والحقول المطلوبة والصيغ).
RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.