Softonic

مدقق مواصفات OpenAPI عبر الإنترنت

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

الصق مواصفة OpenAPI أو Swagger أعلاه للحصول على قائمة بالأخطاء والتحذيرات. تشرح هذه الصفحة معنى كل رسالة وكيفية إصلاحها، حتى تنتقل من تقرير أحمر إلى تقرير نظيف بسرعة. الأخطاء تجعل المستند غير صالح، أما التحذيرات فلا تفعل ذلك.

كيفية فحص المواصفة والتصرف وفق التقرير

  1. 1

    الصق المواصفة

    الصق المستند بصيغة JSON أو YAML في الحقل.

  2. 2

    افتح النتائج

    انتقل إلى خطوة النتائج لترى إما رسالة صلاحية أو قائمة بالأخطاء.

  3. 3

    طابق كل رسالة

    ابحث عن الرسالة في الجدول أدناه وطبّق الإصلاح في ملف المصدر.

  4. 4

    الصق من جديد

    أعد التشغيل حتى لا يبقى أي خطأ، ثم قرر أي التحذيرات يستحق الإصلاح.

قراءة رسائل الأخطاء

الرسالة المعنى الإصلاح
Could not parse as JSON or YAML. النص غير قابل للقراءة بأي من الصيغتين أصلح الصياغة: فواصل زائدة، أو مسافات بادئة خاطئة، أو أقواس غير مغلقة
Missing ‘openapi’ or ‘swagger’ version field. لا يوجد مفتاح إصدار على المستوى الأعلى أضف openapi: 3.0.3 أو swagger: "2.0"
Missing ‘info’ object. لا يوجد قسم info أضف info مع العنوان والإصدار
info.title is required. لا يحتوي info على عنوان أضف title تحت info
info.version is required. لا يحتوي info على إصدار أضف version تحت info (إصدار واجهتك)
Missing ‘paths’ object. لا يوجد قسم paths أضف paths حتى لو كان فارغًا في البداية

الأخطاء هي ما يحدد إن كان المستند صالحًا أم لا. أصلح كل خطأ منها أولًا.

قراءة التحذيرات

الرسالة المعنى الإصلاح
Path ‘x’ should start with ‘/’. مفتاح تحت paths لا يبدأ بشرطة مائلة غيّر اسمه إلى /x
Unknown method ‘x’ on /path. مفتاح تحت مسار غير موجود في القائمة المعروفة تحقق من وجود خطأ مطبعي، أو تجاهله إن كان امتدادًا مقصودًا أو trace

القائمة المعروفة هي get وpost وput وpatch وdelete وhead وoptions وparameters وsummary وdescription وservers. امتدادات المواصفة التي تبدأ بـ x- ليست ضمن هذه القائمة، لذلك تظهر كتحذيرات أيضًا.

ما لا يستطيع الفحص عبر الإنترنت إخبارك به

يغطي التقرير البنية فقط. لا يتتبع روابط $ref، ولا يفحص تعريفات المخططات، ولا يلاحظ غياب قيم operationId. اعتبر النجاح دليلًا على أن الملف بالشكل الصحيح لمستند OpenAPI، واستخدم مدققًا شاملًا قبل نشر الوثائق أو توليد كود العميل.

نصائح للتعامل مع تقرير طويل

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

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

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

ليس بالضرورة. هذا يعني أن البنية على المستوى الأعلى سليمة. المخططات والمراجع والاستجابات لم تُفحص.

تُقارن المفاتيح تحت المسار بقائمة ثابتة من طرق HTTP وبعض حقول عنصر المسار. مفتاح x- ليس ضمنها، لذلك يُعلَّم كتحذير. يمكنك إبقاؤه كما هو.

لا. تتبع الأخطاء ترتيب الفحوص: حقل الإصدار أولًا، ثم info، ثم paths. ولا تظهر أرقام أسطر.

أدوات ذات صلة

مولّد إعدادات 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، وعرض أي اختلافات بين العناصر وأنواعها مع تحديد أرقام السطور بدقة.

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

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