منسّق OpenAPI

تعمل في المتصفح الويب

جمّل مستندات OpenAPI، وبدّل بين YAML وJSON، ورتّب اختيارياً المسارات والطرق والمكوّنات للحصول على مقارنات (diffs) متسقة.

الخصوصية: تعمل هذه الأداة بالكامل في متصفحك. لا تغادر بياناتك جهازك أبداً.

كيفية استخدام منسّق OpenAPI

  1. الصق مستند OpenAPI أو Swagger.
  2. اختر صيغة الإخراج والمسافة البادئة ووضع الترتيب.
  3. انسخ المستند المنسّق أو نزّله (openapi.yaml / openapi.json).

مزايا منسّق OpenAPI

  • التحويل بين JSON وYAML بمسافة بادئة من مسافتين أو 4 مسافات
  • ترتيب بنيوي: المسارات وأسماء المكوّنات والوسوم أبجدياً، وطرق HTTP والمفاتيح العليا بالترتيب القياسي، والاستجابات حسب رمز الحالة
  • صيغة قياسية كاملة اختيارية مع ترتيب كل مفتاح
  • ملخص يعرض الإصدار المكتشف والحجم قبل التنسيق وبعده وحالة التحقق
  • أخطاء تحليل دقيقة برقم السطر للمدخلات غير الصالحة

مثال على منسّق OpenAPI

من JSON مصغّر إلى YAML مرتّب

الإدخال:

{"openapi":"3.0.3","paths":{"/b":{"get":{…}},"/a":{"post":{…},"get":{…}}},"info":{"title":"X","version":"1"}}

النتيجة:

openapi: 3.0.3
info:
  title: X
  version: "1"
paths:
  /a:
    get: …
    post: …
  /b:
    get: …

الأسئلة الشائعة حول منسّق OpenAPI

ما وظيفة خيار «ترتيب المسارات والطرق والمكوّنات»؟

تُرتَّب المسارات وأسماء المكوّنات أبجدياً، وطرق HTTP بالترتيب القياسي (GET وPUT وPOST وDELETE وOPTIONS وHEAD وPATCH وTRACE)، ورموز الاستجابة رقمياً مع وضع default في النهاية، والمفاتيح العليا بترتيب OpenAPI المتعارف عليه. ويبقى المحتوى متطابقاً، فيكون الناتج صيغة قياسية ثابتة للمقارنات.

هل التحويل من YAML إلى JSON خالٍ من الفقد؟

بالنسبة لمستندات OpenAPI، نعم: فهي لا تستخدم إلا المجموعة الفرعية من YAML المتوافقة مع JSON. تُحوَّل التواريخ والقيم الثنائية إلى سلاسل نصية، وتُوسَّع المراسي (anchors) والأسماء البديلة (aliases).

لماذا تُوضع بعض المفاتيح بين علامتي اقتباس في إخراج YAML؟

قد تفسّر محلّلات YAML مفاتيح مثل "200" أو "yes" أو "on" على أنها أعداد أو قيم منطقية، لذا تُقتبس لتبقى سلاسل نصية — وهو بالضبط ما تتوقعه أدوات OpenAPI لرموز الاستجابة.

هل يتحقق المنسّق من الصحة أيضاً؟

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