Softonic

مدقق OpenAPI بصيغة YAML

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

الصق ملف openapi.yaml وستتحقق الأداة من الأجزاء التي تحتاجها كل مواصفة: حقل إصدار، وكائن info يحتوي على عنوان وإصدار، وكائن paths. كما تحذّر من مفاتيح المسارات التي لا تبدأ بشرطة مائلة، ومن مفاتيح العمليات التي لا تتعرف عليها.

كيفية التحقق من ملف OpenAPI بصيغة YAML

  1. 1

    انسخ YAML

    انسخ المحتوى الكامل لملف `openapi.yaml` أو `swagger.yaml`، مع الحفاظ على المسافات البادئة كما هي.

  2. 2

    الصقه في الحقل

    ضعه في حقل مستند OpenAPI / Swagger. في YAML تمثل المسافات البادئة البنية نفسها، لذلك لا تعد كتابته أو إعادة تنسيقه.

  3. 3

    شغّل التحقق

    انتقل إلى خطوة النتائج واقرأ الأخطاء والتحذيرات.

  4. 4

    صحّح وأعد الفحص

    أصلح كل بند ورد في التقرير داخل ملفك، ثم الصق النسخة الجديدة وأعد التشغيل.

لماذا تؤثر المسافات البادئة في النتيجة

في YAML يحدد تداخل المفاتيح الكائن الذي ينتمي إليه كل حقل. إذا وُضع version في المستوى نفسه مع info بدلًا من أن يكون تحته بمستوى واحد، فالنص ما يزال YAML قابلًا للقراءة، لكن info.version يصبح مفقودًا وتبلغ الأداة عنه. وينطبق الأمر نفسه على paths: إذا أُزيح مفتاح مسار تحت info عن طريق الخطأ، يختفي كائن paths على المستوى الأعلى.

استخدم المسافات وليس الجدولة (Tab)، وحافظ على خطوة ثابتة مثل مسافتين لكل مستوى.

مثال عملي

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

حقل الإصدار وinfo.title وpaths موجودة كلها، والمسار /pets يبدأ بشرطة مائلة وتحته العملية المعروفة get. الناقص هنا شيء واحد: info.version. يسرد التقرير:

النتيجة النوع
info.version is required. خطأ

أضف version: 1.0.0 تحت info مع مسافتين بادئتين، وسيُعلن المستند صالحًا بنيويًا.

اجعل المستندات بسيطة لقراءة موثوقة

يقرأ الفحص أفضل ما يقرأه من تراكيب YAML العادية: أزواج key: value بسيطة متداخلة بمسافات بادئة ثابتة. إذا عُدّ مستند يحتوي على ميزات YAML متقدمة، مثل المراسي (anchors) أو الكتل متعددة الأسطر، غير قابل للقراءة أو أظهر حقولًا مفقودة، فجرّب نسخة JSON من المواصفة نفسها لتعرف هل المشكلة في المحتوى أم في صياغة YAML.

النتيجة النظيفة تؤكد الهيكل الأساسي فقط. لا تحل روابط $ref ولا تفحص المخططات.

سير عمل عملي لمواصفات YAML

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

أخيرًا، تذكّر أن التقرير لا يعرض إلا ما يستطيع الفحص رؤيته. النتيجة النظيفة لملف YAML تعني أن الهيكل الأساسي سليم، لا أن كل عملية أو مخطط أو مرجع بداخله سليم.

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

المسافات. لا تقبل YAML الجدولة في التدرج، وقد تجعل الجدولة المستند غير قابل للقراءة أو تنقل الحقول إلى مستوى خاطئ.

غالبًا ما يكون الحقل مُزاحًا إلى مستوى خاطئ، فينتمي إلى كائن آخر غير الذي قصدته. قارن مسافته البادئة بالمفتاح الأب.

يتحقق هذا الفحص من وجود الحقل openapi أو swagger فقط، لا من قيمته، لذلك تنجح الإصدارات المقتبسة وغير المقتبسة على حد سواء. ومع ذلك يُنصح بتعيين "2.0" بين علامات اقتباس في Swagger.

نعم. تُقرأ المدخلات كـ JSON أولًا، وإذا فشل ذلك تُقرأ كـ YAML، لذلك يعمل كلا التنسيقين في الحقل نفسه.

أدوات ذات صلة

مولّد إعدادات Webpack

أنشئ ملف webpack.config.js لـ webpack 5 لمشاريع JavaScript الخالصة أو React أو Vue: مع TypeScript وBabel وCSS أو Sass والصور وHtmlWebpackPlugin وخادم التطوير وسطر npm install.

محوّل ترميز ملفات النصوص

حوّل النص بين UTF-8 وUTF-16 وLatin-1 وWindows-1252 وترميزات أخرى لإصلاح الأحرف المشوّهة.

مولّد ملف .gitignore

اجمع قواعد استبعاد المشروع لـ Laravel وNode.js وPython وRails. انسخ الناتج أو نزّل ملف ZIP يحتوي على .gitignore، مع إبقاء القواعد الشخصية منفصلة.

مرجع جدول ASCII

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

أداة فك ترميز Protocol Buffers

فك ترميز بايتات Protobuf محليًا من hex أو Base64 أو Base64URL أو نص أو ملف، مع فحص دقيق للحقول وتصدير تقرير خاص.

مُحقق تنسيق XSD

قم بالتحقق من وثيقة XML وفقًا لمخطط XSD، وعرض أي اختلافات بين العناصر وأنواعها مع تحديد أرقام السطور بدقة.

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

أدلة وحالات استخدام