إذا أتيت إلى هنا بعد تشغيل npm install -g @apidevtools/swagger-cli ولاحظت التحذيرات، فإليك النسخة المختصرة: الأداة لم تعد قيد الصيانة. يشير مستودع swagger-cli على GitHub بوضوح إلى أنه مهمل، مستشهدًا بـ "عبء الصيانة الناتج عن محاولة مواكبة توقعات قاعدة مستخدمين ضخمة مع مساهمات قليلة أو معدومة." ملف README نفسه يوجهك نحو Redocly CLI كبديل.
لذا أنت بحاجة إلى بديل. هذا يتعلق على وجه التحديد بأداة الطرفية swagger-cli، التي تقوم بـ validate و bundle. إذا كنت تقصد محرر Swagger Editor أو SwaggerHub أو مجموعة التصميم الأوسع، فاقرأ 7 بدائل لـ Swagger تختبر API الخاص بك أيضًا بدلاً من ذلك.
دعنا نلقي نظرة على ما كانت تفعله أداة swagger-cli، ثم نستعرض القائمة المختصرة الصادقة لما يجب استخدامه الآن.
ما كانت تفعله swagger-cli بالفعل
من المهم أن نكون دقيقين، لأن البديل الصحيح يعتمد على ما كنت تستخدمه.
كان لدى swagger-cli بالضبط أمرين:
# التحقق من تعريف Swagger 2.0 / OpenAPI 3.0 مقابل المخطط والتحقق من $refs
swagger-cli validate openapi.yaml
# متابعة مؤشرات $ref ودمج تعريف متعدد الملفات في ملف واحد
swagger-cli bundle openapi.yaml -o bundled.json
كان لأمر bundle مجموعة صغيرة من الخيارات: -o/--outfile للكتابة إلى ملف، -t/--type لاختيار JSON أو YAML، -r/--dereference لتضمين كل $ref بالكامل، و -f/--format للمسافة البادئة.
هذه هي الأداة بالكامل. كانت تتحقق من الهيكل وتجمع المواصفات متعددة الملفات. لم تقم بالتحقق من القواعد الأسلوبية (lint)، أو إنشاء الوثائق، أو تشغيل الاختبارات، أو محاكاة أي شيء. إذا قرأت ادعاءات بأن swagger-cli "تحققت" من مواصفاتك، فهي خاطئة؛ لقد قامت فقط بالتحقق من تعريفك مقابل مخطط OpenAPI وحل المراجع. ضع هذا النطاق في الاعتبار، لأن بعض البدائل تفعل أكثر بكثير، وقد ترغب في ذلك أو لا ترغب.
القائمة المختصرة
تغطي ثلاث أدوات تقريبًا كل الأسباب التي قد تدفعك لاستخدام swagger-cli، بالإضافة إلى أداتين متخصصتين تستحقان الذكر. إليك الملخص الصادق.
Redocly CLI: البديل الرسمي والأقرب 1:1
Redocly CLI (@redocly/cli، الثنائي redocly) هو أداة مفتوحة المصدر، وهو الأداة التي يشير إليها ملف README الخاص بـ swagger-cli. حتى أن Redocly ينشر دليل ترحيل من swagger-cli. إذا كان هدفك هو أداة تحقق ودمج فورية في الطرفية، فابدأ من هنا.
قم بتثبيته بنفس الطريقة التي قمت بها بتثبيت swagger-cli:
npm install -g @redocly/cli@latest
# أو قم بالتشغيل دون تثبيت
npx @redocly/cli@latest lint openapi.yaml
الربط واضح. يصبح validate في swagger-cli هو redocly lint، والذي يتحقق من مواصفاتك ويطبق قواعد الأسلوب القابلة للتكوين. يصبح bundle في swagger-cli هو redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
إليك ربط أعلام التجميع جنبًا إلى جنب:
| swagger-cli | Redocly CLI | الغرض |
|---|---|---|
-o, --outfile |
--output (أو -o) |
الكتابة إلى ملف |
-t, --type |
--ext (json, yaml, yml) |
تنسيق الإخراج |
-r, --dereference |
-d, --dereferenced |
تضمين كل $ref بالكامل |
شيء واحد يجب معرفته: redocly lint يفعل أكثر مما كان يفعله validate في swagger-cli بشكل افتراضي. إنه يطبق مجموعة قواعد دليل الأسلوب، وليس مجرد فحص للمخطط. إذا كنت تريد التحقق الهيكلي البسيط الذي قدمه لك swagger-cli، فقم بتكوين ملف redocly.yaml بقاعدة spec فقط، ثم قم بتشغيل redocly lint openapi.yaml. سلوك مجموعة القواعد هذا هو نقطة قوة Redocly المميزة بدلاً من كونه عيبًا؛ ولهذا السبب تحبه الفرق التي تريد حوكمة محلية للطرفية. يمكنك ضبط مجموعات القواعد (minimal, recommended, recommended-strict, spec) أو كتابة قواعد مخصصة. انظر أفضل إعداد لمحلل OpenAPI لكيفية تناسب ذلك مع المحللين الآخرين.
يتجاوز Redocly CLI أيضًا الأمرين اللذين كانا في swagger-cli. يمكنه split وصفًا واحدًا إلى هيكل متعدد الملفات (عكس التجميع)، و join عدة ملفات (تجريبي)، وبناء وثائق Redoc HTML مستقلة:
redocly build-docs openapi.yaml -o docs.html
ما لا يفعله: تشغيل اختبارات API أو استضافة خادم وهمي. إنها أداة أولاً-كود، طرفية-محلية للتحليل/التجميع/الوثائق، وممتازة. إذا كان هذا كل ما تحتاجه، يمكنك التوقف عن القراءة والترحيل اليوم.
Apidog: عندما تريد أكثر من التحقق والتجميع
هنا إعادة صياغة صادقة. كانت swagger-cli نصًا ثابتًا قمت بتشغيله للتحقق والتجميع. ولكن بالنسبة لمعظم الفرق، فإن التحقق والتجميع هما وسيلتان لتحقيق غاية. أنت تتحقق للتأكد من صحة المواصفات، وتجمعها لتكون قابلة للنقل، ثم تقوم بمحاكاتها واختبارها وتوثيقها. سلمت swagger-cli هذه الخطوات اللاحقة لأدوات أخرى.
Apidog يسد هذه الفجوة. إنه منصة API متكاملة: تصميم، محاكاة، اختبار، ووثائق في مساحة عمل واحدة، مع واجهة سطر أوامر (CLI) تتعامل مع الاستيراد والتصدير وتشغيل اختبارات التكامل المستمر (CI). حيث كانت swagger-cli تمنحك ملفًا، يمنحك Apidog مساحة عمل حية مبنية من هذا الملف.
الأمران اللذان يرتبطان مباشرة بذاكرتك العضلية في swagger-cli هما import و export. قم بتثبيت CLI والمصادقة أولاً:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
يمكنك الحصول على الرمز المميز من تطبيق Apidog أو الويب: الصورة الرمزية، ثم إعدادات الحساب، ثم رمز الوصول إلى API. يتم تخزينه في ~/.apidog/config.toml، لذا لا تقم بطباعته أو الالتزام به أبدًا.
الاستيراد هو خطوة التحقق الخاصة بك. يقوم بإدخال تعريف في مشروع ويحل $refs متعددة الملفات إلى موارد موحدة. إذا كان الملف مشوهًا، يظهره الاستيراد:
apidog import --project 123456 --format openapi --file ./openapi.json
يقبل الاستيراد قائمة طويلة من التنسيقات بخلاف OpenAPI، بما في ذلك Postman و HAR و Insomnia و WSDL و JSON Schema، وهو أمر مفيد عندما تكون مصادرك مختلطة.
التصدير هو خطوة التجميع الخاصة بك، مع مكافأة. ينتج ملفًا موحدًا واحدًا، وتختار إصدار OpenAPI عند الخروج. وهذا يجعله تجميعًا بالإضافة إلى ترقية مواصفات اختيارية في أمر واحد:
# تجميع وترقية إلى OpenAPI 3.1 في خطوة واحدة
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# أو إصدار وثائق HTML مستقلة
apidog export --project 123456 --format html --output ./docs.html
لـ CI، يضيف Apidog الخطوة التي لم تكن موجودة في swagger-cli: تشغيل الاختبارات.
# تشغيل سيناريو اختبار في CI بتنسيقات تقارير متعددة
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# أو تشغيل دون اتصال بالكامل من ملف مجموعة مصدّر
apidog run ./collection.apidog-cli.json
يدير CLI أيضًا موارد المشروع مباشرة، بما في ذلك endpoint و schema و mock و environment و branch و test-suite و test-report. للحصول على تفاصيل الإعداد وكل علامة، راجع الدليل الكامل لـ Apidog CLI و وثائق Apidog CLI الرسمية.
الآن القيود الصادقة، لأن الملاءمة أهم من الضجيج. يتحقق Apidog CLI من الهيكل عند الاستيراد، لكنه لا يوفر لك محلل دليل أسلوب أولاً-كود قابل للتكوين مع مجموعات قواعد مخصصة بالطريقة التي يفعلها lint في Redocly. لا يوجد أمر apidog lint، ولا يمكنك تأليف قواعد مخصصة بأسلوب Spectral عبر CLI. لا يوجد أيضًا split أو join. Apidog يعتمد على الواجهة الرسومية أولاً: التصميم، المحاكاة، بناء الاختبارات المرئية، والوثائق يتم تأليفها بشكل أساسي في تطبيق سطح المكتب أو الويب، مع قيام CLI بالتعامل مع الاستيراد، التصدير، تشغيل اختبارات CI، وإدارة الموارد مقابل المشروع. و Apidog هو نظام "فريميوم" (Freemium)، وليس مفتوح المصدر، لذا فهو نموذج مختلف عن Redocly CLI و Spectral.
Spectral: تحليل نقي وقابل للتخصيص في CI
إذا كان ما كنت تريده حقًا من swagger-cli هو التحقق الصارم والمدفوع بالآراء في مسار عملك، فإن المحلل المخصص هو Spectral من Stoplight. إنه مفتوح المصدر ومصمم لمهمة واحدة: تطبيق مجموعة قواعد قابلة للتخصيص على وثائق OpenAPI (و JSON/YAML الأخرى).
يتألق Spectral عندما تريد فرض أسلوب الشركة ككود، بقواعدك الخاصة، في كل طلب سحب. إنه لا يجمع، ولا يولد وثائق، ولا يختبر نقاط النهاية؛ إنه يقوم بالتحليل (lint). قم بإقرانه بمُجمِّع وستكون قد أعدت بناء نسخة مركزة مما كان يفعله swagger-cli، بالإضافة إلى حوكمة حقيقية. يوضح دليلنا لـ تحليل Spectral OpenAPI كيفية كتابة مجموعات القواعد، و التحقق من OpenAPI في CI يغطي كيفية ربطه بمسار عمل.
باختصار: openapi-generator و vacuum
هناك أداتان أخريان تظهران، لذا إليك النسخة القصيرة والدقيقة. openapi-generator هو مولد للكود والعملاء؛ إذا كان سبب تجميعك هو تغذية مولد، فقد لا تحتاج إلى خطوة تجميع منفصلة على الإطلاق، لأنه يستهلك المواصفات مباشرة. vacuum هو محلل OpenAPI سريع ومتوافق مع Spectral ومكتوب بلغة Go، وهو اختيار جيد عندما تكون سرعة التحليل في المستودعات الكبيرة مهمة. لا يمثل أي منهما بديلاً عامًا للتحقق والتجميع بمفرده، لكن كلاهما يلبي احتياجات محددة.
جدول المقارنة
إليك كيفية ترتيب الخيارات عبر القدرات التي يهتم بها عادةً مستخدمو swagger-cli.
| الأداة | التحقق (Validate) | التجميع (Bundle) | قواعد التحقق (Lint rules) | الوثائق (Docs) | المحاكاة (Mock) | الاختبار (Test) | مفتوح المصدر (Open source) | الأفضل لـ |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | نعم | نعم | لا | لا | لا | لا | نعم (مهملة) | لا شيء جديد؛ لم تعد قيد الصيانة |
| Redocly CLI | نعم (lint) |
نعم | نعم (قابلة للتكوين) | نعم (Redoc HTML) | لا | لا | نعم | تبديل مباشر للتحقق/التجميع في الطرفية مع الحوكمة |
| Apidog | نعم (عند الاستيراد) | نعم (عند التصدير، مع ترقية OAS) | هيكلية فقط، لا توجد مجموعات قواعد مخصصة | نعم (التطبيق + التصدير) | نعم | نعم (تشغيل CLI) | لا (فريميوم) | أداة واحدة لدورة حياة API بأكملها |
| Spectral | نعم (قائم على التحقق) | لا | نعم (مجموعات قواعد مخصصة) | لا | لا | لا | نعم | تحقق صارم وقابل للتخصيص في CI |
| vacuum | نعم (قائم على التحقق) | لا | نعم (متوافق مع Spectral) | لا | لا | لا | نعم | تحقق سريع للمواصفات الكبيرة |
التوصية
هذا ليس موقف "كل شيء رائع، اختر ما تفضله". هناك مساران واضحان يغطيان تقريبًا الجميع.
اختر Redocly CLI إذا كنت تريد بديلاً مباشرًا. إنه البديل الرسمي، ومفتوح المصدر، والترحيل يكاد يكون ميكانيكيًا: validate إلى lint، bundle إلى bundle، مع ربط الأعلام المذكور أعلاه. إذا كان سير عملك هو بالفعل "التحقق والتجميع من الطرفية"، وكنت ترغب في إضافة قواعد حوكمة لاحقًا دون تغيير الأدوات، فإن Redocly هو الخيار الواضح. إنه يبقيك أولاً-كود ومحليًا للطرفية، وهو بالضبط المكان الذي عاشت فيه swagger-cli.
اختر Apidog إذا كان التحقق والتجميع مجرد البداية. معظم الفرق لا تتحقق من مواصفات لمجرد التحقق. إنهم يتحققون منها، ثم يحتاج شخص ما إلى محاكاة للبناء عليها، ويكتب شخص آخر اختبارات، وشخص ما يمتلك الوثائق. توقفت swagger-cli عند الخطوة الأولى وجعلتك تجمع البقية من Spectral ومُجمِّع و Postman و Newman. يجمع Apidog الاستيراد (التحقق)، التصدير (التجميع بالإضافة إلى ترقية إصدار OAS)، المحاكاة، الاختبار، والوثائق في مساحة عمل واحدة، مع واجهة سطر أوامر (CLI) للأجزاء التي تنتمي إلى CI. تتوقف عن رعاية نص ثابت، مهمل الآن، وتجلب المواصفات بأكملها إلى مكان يظل فيه مفيدًا بعد تجميعها.
هذه نماذج مختلفة، وليست نسخًا متنافسة من نفس الشيء. Redocly CLI هي الأداة المتخصصة خفيفة الوزن، مدفوعة بالتكوين، والتي تشغلها فقط من الطرفية. Apidog هي المنصة الشاملة التي تصادف أن لديها واجهة سطر أوامر قوية. اختر بناءً على مقدار دورة الحياة التي تريدها في أداة واحدة، وكن صادقًا بشأن ذلك: إذا كنت تريد فقط تحليل وتجميع في الطرفية، فإن Redocly أكثر رشاقة ومجانًا.
إذا كنت ترغب في تجربة نهج دورة الحياة، قم بتنزيل Apidog واستيراد مواصفات موجودة؛ إنه مجاني للبدء، ولا يتطلب بطاقة ائتمان، ويمكنك رؤية إخراجك المجمع والمُنسّخ في بضع دقائق.
الأسئلة الشائعة
هل لا تزال swagger-cli قيد الصيانة؟
لا. مستودع swagger-cli على GitHub معلم كمهمل ولم يعد قيد الصيانة، مستشهدًا بانخفاض المساهمات مقابل قاعدة مستخدمين كبيرة. لا يزال يتم تثبيته وتشغيله، لكنه لن يتلقى إصلاحات أو تحديثات، لذا خطط لعملية ترحيل.
ما الذي حل محل swagger-cli؟
يشير ملف README الخاص بالمشروع إلى Redocly CLI كبديل. يحل redocly lint محل swagger-cli validate ويحل redocly bundle محل swagger-cli bundle. حتى أن Redocly تنشر دليل ترحيل مخصص. إذا كنت تريد أكثر من التحقق والتجميع، يغطي Apidog الاستيراد والتصدير والمحاكاة والاختبار والوثائق في مكان واحد.
هل Apidog مجاني؟
Apidog هو نظام فريميوم. توجد طبقة مجانية يمكنك البدء بها دون الحاجة إلى بطاقة ائتمان، مع خطط مدفوعة للفرق الأكبر والاحتياجات المتقدمة. إنه ليس مفتوح المصدر، وهو الفارق الرئيسي عن Redocly CLI و Spectral إذا كان الترخيص المفتوح متطلبًا بالنسبة لك.
هل يمكنني الاحتفاظ بسير عمل swagger-cli الخاص بي كما هو بالضبط؟
الأقرب هو Redocly CLI. لتعكس وظيفة validate الهيكلية البسيطة لـ swagger-cli، قم بإعداد ملف redocly.yaml بقاعدة spec فقط وقم بتشغيل redocly lint. للتجميع، تتطابق الأوامر والأعلام تقريبًا واحدًا لواحد. للحصول على نظرة أعمق على نطاق الأداة الأصلية، راجع كيفية استخدام swagger-cli من الطرفية.