YAML للكتابة والتأليف
تُقرأ الأوصاف الطويلة بشكل أفضل ككتل نصية في YAML، وتتيح لك التعليقات إضافة ملاحظات على المواصفة للمراجعين.
حوّل مواصفات API بين JSON وYAML دون كسر مسارات $ref أو رموز الاستجابة.
كل سطر من الناتج، بالتنسيق الافتراضي، بجانب مسار القيمة التي يحملها. انقر على صف لنسخ المسار.
يعمل بالكامل داخل متصفحك: لا يُرفع أي شيء. تُطبَّق حدود الاستخدام العادل (5 MB لكل إدخال، وعدد محدود من عمليات التحويل) لمنع الرسائل المزعجة والبوتات.
تفصيلان يكسران المواصفات المحوّلة يدويًا: علامة # التي تبدأ تعليقًا في YAML، ورموز الحالة التي تصبح أعدادًا صحيحة. ويتولى المحوّل الأمرين كليهما.
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} paths:
/pets/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4XX:
description: Client error اختر يدويًا، دون علامات اقتباس لترى $ref يتحوّل إلى null ويفشل تحليل المضيف ذي الرمز البدل (wildcard).
بعد التحويل، شغّل أداة فحص (linter) لتتحقق من المواصفة نفسها، لا من صياغتها فقط. وهنا يُفحص كل $ref محلي أثناء التحرير.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml تُقرأ الأوصاف الطويلة بشكل أفضل ككتل نصية في YAML، وتتيح لك التعليقات إضافة ملاحظات على المواصفة للمراجعين.
غالبًا ما تحمّل مولّدات الشيفرة والبوابات وحزم SDK صيغة JSON بشكل أسرع، وكثير منها يقدّم المواصفة على /openapi.json.
تصف الصيغتان واجهة API نفسها. حوّل بحرية في أي اتجاه؛ فلا يضيع أي شيء من المواصفة.
محوّلات ومدقّقات وأدلة خطوة بخطوة لكل موضع يلتقي فيه JSON وYAML.
الصق openapi.json أو ارفعه، وانسخ YAML من لوحة المخرجات، أو نزّله باسم openapi.yaml. تبقى البنية ومؤشرات $ref والأمثلة والأوصاف كما هي تمامًا.
نعم. يعمل المحوّل على بنية المستند، لذا تُحوَّل مواصفات Swagger 2.0 وOpenAPI 3.0 وOpenAPI 3.1 بالطريقة نفسها، في الاتجاهين.
في YAML، تبدأ # تعليقًا إذا جاءت بعد مسافة. ودون علامات اقتباس، سيُعامل كل ما بعد $ref: على أنه تعليق ويصبح المرجع فارغًا. ويقتبسها المحوّل تلقائيًا.
يشترط OpenAPI أن تكون رموز الاستجابة مفاتيح نصية. والعدد 200 دون اقتباس عدد صحيح في YAML؛ تقبله معظم الأدوات، لكن أدوات التحقق الصارمة لا تقبله. والاقتباس يبقي المواصفة صالحة في كل مكان.
بدّل الاتجاه إلى YAML → JSON باستخدام زر التبديل أعلى المحرّر، أو استخدم محوّل YAML إلى JSON. تُوسَّع المراسي الموجودة في YAML، لأن JSON لا يملك مراجع من هذا النوع.