OpenAPI وSwagger: من JSON إلى YAML

حوّل مواصفات API بين JSON وYAML دون كسر مسارات $ref أو رموز الاستجابة.

خيارات المخرجات

JSONالمدخلات

فارغ

YAMLالمخرجات

تظهر مخرجات YAML هنا

يعمل بالكامل داخل متصفحك: لا يُرفع أي شيء. تُطبَّق حدود الاستخدام العادل (5 MB لكل إدخال، وعدد محدود من عمليات التحويل) لمنع الرسائل المزعجة والبوتات.

تحميل من URL

يجلب متصفحك الملف مباشرةً، لذا يجب أن يسمح الخادم بالطلبات عبر المصادر (cross-origin).

اختصارات لوحة المفاتيح

Ctrl / ⌘ + Enter التحويل الآن
Ctrl / ⌘ + S تنزيل المخرجات
Alt + Shift + C نسخ المخرجات
Alt + Shift + F إصلاح مدخلات JSON وتنسيقها
Alt + Shift + S تبديل الاتجاه
Alt + Shift + T التبديل بين عرض الشيفرة والشجرة والخريطة
Ctrl / ⌘ + Z تراجع، بما في ذلك «تنسيق» و«إصلاح» و«مسح»
Esc الخروج من ملء الشاشة
حجم النص في المحرّر

مؤشرات $ref ورموز الاستجابة تبقى صالحة

تفصيلان يكسران المواصفات المحوّلة يدويًا: علامة # التي تبدأ تعليقًا في YAML، ورموز الحالة التي تصبح أعدادًا صحيحة. ويتولى المحوّل الأمرين كليهما.

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
paths:
  /pets/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4XX:
          description: Client error

اختر يدويًا، دون علامات اقتباس لترى $ref يتحوّل إلى null ويفشل تحليل المضيف ذي الرمز البدل (wildcard).

افحص النتيجة بأداة lint

بعد التحويل، شغّل أداة فحص (linter) لتتحقق من المواصفة نفسها، لا من صياغتها فقط. وهنا يُفحص كل $ref محلي أثناء التحرير.

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

JSON أم YAML لمواصفات API؟

YAML للكتابة والتأليف

تُقرأ الأوصاف الطويلة بشكل أفضل ككتل نصية في YAML، وتتيح لك التعليقات إضافة ملاحظات على المواصفة للمراجعين.

JSON للأدوات

غالبًا ما تحمّل مولّدات الشيفرة والبوابات وحزم SDK صيغة JSON بشكل أسرع، وكثير منها يقدّم المواصفة على /openapi.json.

المستند نفسه

تصف الصيغتان واجهة API نفسها. حوّل بحرية في أي اتجاه؛ فلا يضيع أي شيء من المواصفة.

مزيد من الأدوات

محوّلات ومدقّقات وأدلة خطوة بخطوة لكل موضع يلتقي فيه JSON وYAML.

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

كيف أحوّل ملف OpenAPI بصيغة JSON إلى YAML؟

الصق openapi.json أو ارفعه، وانسخ YAML من لوحة المخرجات، أو نزّله باسم openapi.yaml. تبقى البنية ومؤشرات $ref والأمثلة والأوصاف كما هي تمامًا.

هل يعمل مع Swagger 2.0 إلى جانب OpenAPI 3؟

نعم. يعمل المحوّل على بنية المستند، لذا تُحوَّل مواصفات Swagger 2.0 وOpenAPI 3.0 وOpenAPI 3.1 بالطريقة نفسها، في الاتجاهين.

لماذا تُقتبس $ref: '#/components/...'؟

في YAML، تبدأ # تعليقًا إذا جاءت بعد مسافة. ودون علامات اقتباس، سيُعامل كل ما بعد $ref: على أنه تعليق ويصبح المرجع فارغًا. ويقتبسها المحوّل تلقائيًا.

لماذا تُكتب رموز الاستجابة بالشكل '200'؟

يشترط OpenAPI أن تكون رموز الاستجابة مفاتيح نصية. والعدد 200 دون اقتباس عدد صحيح في YAML؛ تقبله معظم الأدوات، لكن أدوات التحقق الصارمة لا تقبله. والاقتباس يبقي المواصفة صالحة في كل مكان.

كيف أحوّل OpenAPI من YAML إلى JSON مجددًا؟

بدّل الاتجاه إلى YAML → JSON باستخدام زر التبديل أعلى المحرّر، أو استخدم محوّل YAML إلى JSON. تُوسَّع المراسي الموجودة في YAML، لأن JSON لا يملك مراجع من هذا النوع.