مدقّق OpenAPI

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

تحقق من الحقول المطلوبة، وبنية المسارات والعمليات، وتعريفات المعاملات، ومراجع $ref غير المحلولة، ومعرّفات العمليات المكرّرة، والاستجابات المفقودة، والأخطاء الشائعة في مواصفات OpenAPI / Swagger.

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

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

  1. الصق المواصفة.
  2. اقرأ سطر الحالة، ثم أصلح الأخطاء أولاً (لأنها تعطّل الأدوات) والتحذيرات ثانياً.
  3. نزّل جدول المشكلات بصيغة 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.

الأسئلة الشائعة حول مدقّق 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 بحيث يمكن استخدامها مباشرة مع الأدوات الأخرى. والمدقّق بنيوي وسريع عمداً (تمريرة واحدة دون اتصال بالشبكة)، ما يجعله مناسباً للتحقق الحي أثناء التحرير.