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 تفعل ذلك.

أدوات ذات صلة

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

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

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

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

مرجع جدول ASCII

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

مولّد ملف .gitignore

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

مُحقق تنسيق XSD

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

مولد ملف tsconfig.json

أنشئ ملف tsconfig.json نظيفا باختيار target وmodule وmoduleResolution وJSX وأعلام الصرامة الشائعة، ثم انسخ الإعداد المولّد إلى مشروعك.

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