Softonic

مدقّق OpenAPI

خطوة 1 / 2
التالي

الصق مستند OpenAPI أو Swagger، بصيغة JSON أو YAML، ويفحص هذا المدقّق بنيته الأساسية. يتأكّد من أن المستند يُحلَّل، وأنه يحمل حقل إصدار openapi أو swagger، وكائن info يحوي عنوانًا وإصدارًا، وكائن paths، ثم يشير إلى المسارات التي لا تبدأ بشرطة مائلة وطرق HTTP غير المعروفة. إنه فحص بنيوي سريع، وليس مدقّق JSON Schema كاملًا.

كيف يجري التدقيق

  1. 1

    الصق المستند

    JSON أو YAML، لـ OpenAPI 2 (Swagger) أو OpenAPI 3.

  2. 2

    حلّله

    يحلّل المدقّق المستند بصيغة JSON، ويتراجع إلى تحليل YAML إذا فشل ذلك.

  3. 3

    افحص الحقول المطلوبة

    يتأكّد من حقل إصدار `openapi` أو `swagger`، وكائن `info` يحوي `title` و`version`، وكائن `paths`.

  4. 4

    افحص المسارات

    يُفحَص كل مسار للتأكّد من وجود شرطة مائلة في بدايته، ويُفحَص كل مفتاح عملية مقابل طرق HTTP المعروفة.

  5. 5

    اقرأ التقرير

    الأخطاء تمنع الصحة؛ والتحذيرات تشير إلى المسارات بلا شرطة مائلة بادئة والطرق غير المعروفة.

ما الذي يفحصه هذا المدقّق

الفحص النتيجة عند الفشل
المستند يُحلَّل كـ JSON أو YAML خطأ
وجود حقل openapi أو swagger خطأ
وجود كائن info خطأ
وجود info.title خطأ
وجود info.version خطأ
وجود كائن paths خطأ
كل مسار يبدأ بـ / تحذير
مفاتيح العمليات طرق HTTP معروفة تحذير

المستند الذي يتجاوز كل خطأ يُبلَّغ عنه كصحيح بنيويًا. التحذيرات لا تمنع الصحة؛ إنها تسلّط الضوء على أمور تستحق الإصلاح.

ما الذي لا يفحصه

هذا فحص بنيوي، وليس مدقّق مواصفات كاملًا. إنه لا:

  • يدقّق كل عقدة مقابل مخطط JSON Schema الرسمي لإصدارك؛
  • يحلّ إحالات $ref أو يتأكّد من وجود المكونات التي تشير إليها؛
  • يتحقّق من أن معاملات المسار معلنة ومستخدمة باتساق؛
  • يتحقّق من وجود قيم operationId أو تفرّدها؛
  • يبلّغ عن أرقام الأسطر للأخطاء.

للحصول على هذا العمق، شغّل مدقّق سطر أوامر مخصّصًا مثل redocly lint أو swagger-cli validate أو spectral lint. استخدم هذه الأداة لفحص سريع للسلامة قبل أن تحفظ مواصفة أو تشاركها.

إصدارات OpenAPI المتداولة

الإصدار ملاحظات
Swagger 2.0 لا يزال منتشرًا على نطاق واسع؛ يستخدم swagger: "2.0"
OpenAPI 3.0.x الخط الأكثر شيوعًا في 3.x
OpenAPI 3.1.0 يتوافق مع JSON Schema 2020-12

يقبل هذا المدقّق إما حقل openapi (3.x) أو حقل swagger (2.0)، لذا تجتاز كل هذه فحص الإصدار.

مستند بسيط يجتاز الفحص

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

كل حقل مطلوب موجود، والمسار الوحيد يبدأ بشرطة مائلة، وget طريقة معروفة، لذا يُبلَّغ عن هذا كصحيح بنيويًا.

الأسئلة الشائعة

كان Swagger هو الاسم الأصلي للمواصفة، الذي تُبرِّع به لمؤسسة Linux عام 2015 وأُعيدت تسميته إلى «OpenAPI» بدءًا من الإصدار 3.0. يشير «Swagger» الآن إلى الأدوات (Swagger UI و Swagger Editor). أما المواصفة نفسها فهي OpenAPI. يقبل هذا المدقّق حقلي الإصدار swagger (2.0) وopenapi (3.x) معًا.

لا. يفحص البنية الأساسية: أن المستند يُحلَّل، ويحمل حقل إصدار وكائن info بعنوان وإصدار وكائن paths، ويحذّر من المسارات بلا شرطة مائلة بادئة والطرق غير المعروفة. لا يدقّق كل عقدة مقابل مخطط JSON Schema الرسمي. استخدم redocly lint أو spectral lint لذلك.

لا. لا يتتبّع إحالات $ref ولا يتحقّق من وجود المكونات التي تشير إليها. للإحالات عبر الملفات، جمّع المستند أولًا بأداة مثل redocly bundle أو swagger-cli bundle، ثم شغّل مدقّقًا كاملًا.

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

أدوات ذات صلة

مرجع جدول ASCII

جدول ASCII كامل من 0 إلى 127 مع التمثيل العشري والست عشري والثماني والثنائي والمرجع الرقمي في HTML لكل محرف، بما في ذلك أكواد التحكم مثل NUL وLF وDEL.

مرجع أحرف HTML

قائمة قابلة للبحث بكيانات HTML، مع رموزها المسمّاة والرقمية، بالإضافة إلى خيار النسخ بنقرة واحدة للأحرف والرموز الخاصة.

مرجع اختصارات لوحة المفاتيح

ابحث في الاختصارات الافتراضية الموثقة لـ VS Code وChrome وBash مع GNU Readline على macOS وWindows وLinux.

مدقق البريد الإلكتروني

تحقق من عنوان بريد إلكتروني: فحص صياغة RFC 5322، واستعلام حي عن سجل MX، بالإضافة إلى تفاصيل الجزء المحلي والنطاق والطول. لا يتم إرسال أي بريد.

عدّاد FPS

قِس معدل الإطارات FPS في المتصفح عبر requestAnimationFrame: تنعيم، وأدنى وأقصى معدل إطارات، وحد تنبيه، ورسم بياني اختياري. يعمل محليًا بلا رفع ملفات وبلا API.

مولد EditorConfig

أنشئ ملف .editorconfig بقواعد نمط المسافة البادئة وحجمها ونهاية السطر ومجموعة الأحرف والمسافات البيضاء، لتنسيق موحّد عبر بيئات التطوير المتكاملة (IDEs) والمحررات.

الأداة متاحة بلغات أخرى