عارض OpenAPI

تعمل في المتصفح الويب

الصق مستند OpenAPI لاستكشاف المسارات والعمليات والمعاملات ومتون الطلبات والاستجابات والمخططات (schemas) في عرض نظيف سهل التنقل، بالكامل على جانب العميل.

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

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

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

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

كيفية استخدام عارض OpenAPI

  1. الصق المواصفة أو انقر «تحميل مثال».
  2. انقر «عرض» (أو اضغط Ctrl/Cmd+Enter).
  3. استخدم المرشّح للعثور على نقطة نهاية ووسّعها لقراءة معاملاتها واستجاباتها.

مزايا عارض OpenAPI

  • OpenAPI 3.0/3.1 وSwagger 2.0 بصيغة JSON أو YAML، مع تحليل يجري بالكامل في المتصفح
  • العمليات مجمّعة حسب الوسم (tag) مع شارات الطريقة والمسار والملخص وعلامات الإهمال (deprecation) والمصادقة
  • تفاصيل قابلة للتوسيع: المعاملات ومتن الطلب والاستجابات لكل رمز حالة والأمان وأزرار النسخ
  • المخططات مع جداول الخصائص وJSON الخام، ومخططات الأمان، والخوادم
  • مرشّح فوري عبر الطرق والمسارات ومعرّفات العمليات (operationId) والوسوم وأسماء المخططات؛ مع توسيع/طي الكل
  • تُعرض المشكلات البنيوية في شريط تحذير دون حجب العرض

مثال على عارض OpenAPI

استكشاف واجهة API صغيرة

الإدخال:

openapi: 3.0.3
paths:
  /books:
    get:
      summary: List books
      responses:
        "200": { description: OK }

النتيجة:

default (1)
  GET /books — List books
    Responses: 200 OK

الأسئلة الشائعة حول عارض OpenAPI

ما الصيغ التي يمكنني لصقها؟

OpenAPI 3.0 و3.1 إضافة إلى Swagger 2.0، بصيغة JSON أو YAML. يُكتشف الإصدار من الحقل openapi / swagger.

كيف تُنظَّم العمليات؟

حسب الوسم، بترتيب إعلان الوسوم، مع وضع العمليات غير الموسومة تحت «default». وتتوسّع كل عملية لعرض المعاملات (الاسم والموقع والنوع وهل هي مطلوبة)، ومتن الطلب مع أنواع المحتوى والمخطط، والاستجابات لكل رمز حالة، ومتطلبات الأمان.

هل تُحلّ مراجع $ref؟

تُعرض المراجع المحلية (#/components/schemas/Name و#/definitions/Name) بالاسم، ويسرد قسم المخططات كل مكوّن مع خصائصه وJSON الخام. أما مراجع الملفات الخارجية فتُعرض كما هي.

هل يمكنني البحث داخل مواصفة كبيرة؟

نعم. يطابق مربع المرشّح الطريقة والمسار والملخص وoperationId والوسوم وأسماء المخططات. استخدم «توسيع الكل» / «طي الكل» لفتح جميع الأقسام أو إغلاقها.

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

يبني العارض نموذجاً مطبَّعاً مشتركاً مع المدقّق: الوسوم ← العمليات ← المعاملات/requestBody/الاستجابات، والمكوّنات ← المخططات. وتُحلّ مؤشرات $ref المحلية عبر JSON Pointer؛ وتُلخَّص تسميات المخططات (array<Book> وstring(uuid) وenum(a, b)) حتى تبقى الجداول مقروءة.

المراجع

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