Softonic

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

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

قبل أن تسلّم وصف واجهة برمجية لزميل أو عميل أو أداة توليد وثائق، تأكد من وجود الحقول المطلوبة. الصق المستند أعلاه، وستؤكد الأداة حقل الإصدار وinfo.title وinfo.version وpaths، وتسرد أي حقل ناقص.

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

  1. 1

    الصق المستند

    الصق المواصفة بصيغة JSON أو YAML، حتى لو كانت ما تزال قيد الإعداد.

  2. 2

    شغّل الفحص

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

  3. 3

    أضف ما ينقص

    أضف الحقول المذكورة إلى ملفك باستخدام المقتطفات الواردة أدناه.

  4. 4

    أعد الفحص

    الصق المواصفة بعد التحديث وأعد تشغيل الفحص حتى لا تظهر أي أخطاء.

القطع الأربع المطلوبة

الحقل مكانه مثال
حقل الإصدار المستوى الأعلى openapi: 3.0.3 أو swagger: "2.0"
info.title داخل info title: Orders API
info.version داخل info version: 1.0.0
paths المستوى الأعلى paths: مع مسار واحد على الأقل

قيمة info.version هي إصدار واجهتك أنت، لا إصدار مواصفة OpenAPI. يغفل كثيرون هذا الحقل لأن إصدار المواصفة مكتوب بالفعل في أعلى الملف.

مثال عملي يفتقد كل شيء

servers:
  - url: https://api.example.com

هذا المستند الصغير لا يحتوي على أي عنصر من العناصر المطلوبة. يسرد التقرير ثلاثة أخطاء:

النتيجة النوع
Missing ‘openapi’ or ‘swagger’ version field. خطأ
Missing ‘info’ object. خطأ
Missing ‘paths’ object. خطأ

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

هيكل أولي للبدء

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

يجتاز هذا الهيكل كل فحوص الحقول المطلوبة. استبدل الأسماء بأسمائك وابنِ عليه. الاستجابات والمخططات والأمان ليست جزءًا من هذا الفحص.

متى تشغّل هذا الفحص

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

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

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

لا. يحدد الحقل openapi إصدار المواصفة التي تستخدمها. أما info.version فهو إصدار واجهتك أنت، مثل 1.0.0.

يجب أن يوجد المفتاح ككائن، ولا يشترط هذا الفحص وجود مسارات داخله. أضف مسارات حقيقية قبل النشر.

لا تعمل فحوص العنوان والإصدار إلا عند وجود كائن info. أضفه ثم أعد التشغيل لترى إن كانت حقوله مكتملة.

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

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

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