Redocly CLI هي أداة جيدة. إذا كنت قد استخدمتها لتدقيق ملفات OpenAPI، أو تجميع مواصفات متعددة الملفات في ملف واحد، أو بناء مستندات Redoc من الطرفية، فأنت تعلم ذلك بالفعل. فلماذا تبحث عن بديل لـ Redocly CLI من الأساس؟
عادةً ما يتعلق الأمر بالشكل. Redocly CLI هو متخصص يركز على الكود أولاً: التدقيق، التجميع، التقسيم، الدمج، بناء المستندات. هذا يناسب بعض الفرق تمامًا، ولا يكفي لفرق أخرى. إذا كنت تريد أداة واحدة تقوم أيضًا بتصميم واجهة برمجة التطبيقات (API) الخاصة بك، ومحاكاتها، واختبارها، فإن واجهة سطر الأوامر (CLI) لا تحاول أن تكون هذه الأداة، ولا ينبغي لها ذلك.
يتناول هذا المقال **Redocly CLI** (الحزمة مفتوحة المصدر @redocly/cli)، وليس منتج مستندات Redocly المستضاف. إذا كنت تقارن منصة المستندات المستضافة أو Redoc نفسه، فاقرأ بدلاً من ذلك مراجعتنا لبدائل Redocly لتوثيق واجهة برمجة التطبيقات. هذه المقالة مخصصة للأشخاص الذين يكتبون redocly lint و redocly bundle ويريدون معرفة ما يناسب سير عملهم أيضًا.
ما الذي يتقنه Redocly CLI حقًا
Redocly CLI هو برنامج مفتوح المصدر ومتوافق أصلاً مع الطرفية. تقوم بتثبيته مرة واحدة وتحصل على مجموعة متكاملة من الأوامر التي تؤدي وظائفها بسلاسة. تغطي وثائق Redocly CLI كل هذه الأوامر، ولكن إليك نسخة مختصرة.
التدقيق هو نقطة قوتها المميزة. يقوم redocly lint بالتحقق من صحة وصف OpenAPI أو AsyncAPI أو Arazzo أو Open-RPC الخاص بك ثم يقوم بتشغيل قواعد دليل الأنماط فوقه. يمكنك تكوين كل شيء عبر ملف redocly.yaml: اختر مجموعة قواعد مدمجة (minimal، recommended، recommended-strict، أو spec) أو قم بإنشاء قواعدك المخصصة. هذه الحوكمة القائمة على التكوين يصعب التغلب عليها إذا كنت تريد فرض تصميم API متناسق في التكامل المستمر (CI) عبر فرق متعددة.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
التجميع والتقسيم والدمج تتعامل مع إدارة المواصفات. يتبع redocly bundle مؤشرات $ref وينتج ملفًا موحدًا واحدًا. يقوم redocly split بالعكس، حيث يفصل وصفًا واحدًا إلى تخطيط متعدد الملفات. يقوم redocly join (تجريبي) بدمج ملفات OpenAPI متعددة في ملف واحد.
redocly bundle openapi.yaml --output dist/openapi.json
يتم إنشاء المستندات بواسطة build-docs. ينتج صفحة HTML مستقلة لـ Redoc، ويوفر preview-docs معاينة محلية مباشرة لك.
redocly build-docs openapi.yaml -o docs.html
لذلك، إذا كانت احتياجاتك هي "التحقق من صحة المواصفات وفقًا لدليل الأنماط، وتجميع المواصفات، ونشر مستندات Redoc، وكل ذلك من الطرفية"، فإن Redocly CLI هو خيار افتراضي قوي. يجب على العديد من الفرق الاحتفاظ به. أسباب البحث عن بدائل أخرى تتعلق بالنطاق، لا بالجودة.
لماذا يبحث الناس عن بديل
تظهر بعض الأنماط مرارًا وتكرارًا:
- تريد منصة شاملة، وليس مجرد تدقيق بالإضافة إلى توثيق. لا يقوم Redocly CLI بتشغيل اختبارات API ولا يستضيف خادم محاكاة. إذا كنت تحتاج أيضًا إلى تصميم ومحاكاة ومشغل اختبارات، فأنت تقوم بتجميع سلسلة أدوات حوله.
- تريد واجهة رسومية للمستخدم (GUI) بجانب واجهة سطر الأوامر (CLI). Redocly مصمم ليكون معتمدًا على الكود أولاً. إذا كان فريقك يضم أشخاصًا يفضلون العمل بشكل مرئي، فإن الحوكمة القائمة على الطرفية فقط قد تكون صعبة الإقناع.
- تريد مشغل اختبارات مدمج للتكامل المستمر (CI). يلتقط التدقيق مشاكل المواصفات. ولكنه لا يخبرك ما إذا كانت واجهة برمجة التطبيقات (API) قيد التشغيل تعمل بشكل صحيح. هذه أداة منفصلة.
- لا تريد تجميع خمس أدوات معًا. Spectral للتدقيق، Redocly للتجميع والتوثيق، Postman أو Newman للاختبارات، وشيء آخر للمحاكاة. هذا يعمل، لكنه يتطلب الكثير من الأجزاء المتحركة للحفاظ عليها.
كل من هذه النقاط تشير إلى بديل مختلف. دعنا نطابقها.
القائمة المختصرة، بناءً على ما تريده بالفعل
Apidog، إذا كنت تريد منصة واحدة لدورة حياة API بأكملها
Apidog هي منصة API شاملة: تصميم، محاكاة، اختبار، وتوثيق في مكان واحد، مع واجهة سطر أوامر (CLI) للاستيراد والتصدير وتشغيل اختبارات CI. إنه الخيار الصحيح عندما تفضل امتلاك أداة واحدة لدورة الحياة بأكملها بدلاً من ربط مدقق، ومُجمِّع، ومشغل اختبارات، وخادم محاكاة معًا.
هذا هو الجزء الصريح. لا يحتوي Apidog على مدقق دليل أنماط قابل للتكوين ويعتمد على الكود أولاً مع مجموعات قواعد مخصصة مثل lint في Redocly. لا يوجد أمر apidog lint ولا توجد طريقة لإنشاء قواعد مخصصة بأسلوب Spectral أو Redocly عبر واجهة سطر الأوامر. يتحقق Apidog من البنية عند استيراد المواصفات، ولكن إذا كانت الحوكمة الصارمة والقابلة للتخصيص للتصميم هي الشيء الوحيد الذي تهتم به، فلن يحل Apidog محل redocly lint بمفرده. قم بإقرانه بـ Spectral لهذه المهمة. سنعود إلى هذا لاحقًا.
ما يوفره لك Apidog ولا يوفره Redocly CLI: مصمم مرئي، خادم محاكاة مدمج، أداة بناء اختبار مرئية، ومشغل اختبار CI. تتعامل واجهة سطر الأوامر (CLI) مع الأجزاء التي تنتمي إلى الطرفية.
# Install and authenticate (token from the app: avatar > Account Settings > API Access Token)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Import a spec into a project (validates + resolves multi-file $refs)
apidog import --project 123456 --format openapi --file ./openapi.json
# Export a single consolidated file, and pick your OpenAPI version
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Run a test scenario in CI with multiple report formats
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
يقوم apidog import بمهمة التحقق عند الاستيعاب، ويقوم apidog export بمهمة التجميع عند التصدير (يصدر ملفًا واحدًا ويمكنه ترقية إصدار OAS). توجد قائمة الأوامر الكاملة في وثائق Apidog CLI، ويشرح دليلنا الشامل لـ Apidog CLI كل علامة. الأفضل لـ: الفرق التي تريد تصميمًا ومحاكاة واختبارًا وتوثيقًا تحت سقف واحد.
Spectral، إذا كان كل ما تريده من Redocly هو المدقق
إذا كان الشيء الوحيد الذي تستخدمه هو redocly lint، فلا داعي لتبديل المنصات. Spectral من Stoplight هو المدقق مفتوح المصدر القائم على القواعد والذي يتداخل بشكل مباشر مع تدقيق Redocly. تكتب القواعد في YAML، وتقوم بتشغيلها مقابل أي مستند OpenAPI أو AsyncAPI، وتربطها بـ CI.
مدقق Spectral ومدقق Redocly قريبان من بعضهما. كلاهما يعتمد على التكوين، وكلاهما يوفر مجموعات قواعد، وكلاهما يسمح لك بإنشاء قواعد مخصصة. غالبًا ما يعتمد الاختيار بينهما على ملاءمة النظام البيئي وتنسيق مجموعة القواعد الذي يعرفه فريقك بالفعل. يغطي تحليلنا المتعمق لـ تدقيق Spectral OpenAPI إنشاء القواعد، ويقارن الدليل الأوسع لتدقيق API مشهد التدقيق إذا كنت تريد الصورة الكاملة. الأفضل لـ: الفرق التي تحتاجها الحقيقية هي تدقيق المواصفات النقي والقابل للتخصيص.
Scalar أو Bump.sh، إذا كنت تريد التوثيق بشكل أساسي
إذا كان الجزء الذي اهتممت به من Redocly CLI هو build-docs، فإن البديل هو أداة توثيق، وليس منصة. يقوم كل من Scalar و Bump.sh بتحويل وصف OpenAPI إلى مستندات مرجعية مستضافة وقابلة للتصفح، لكل منها مظهرها الخاص ومجموعة ميزاتها. يركزان على تجربة التوثيق بدلاً من التدقيق أو الاختبار. الأفضل لـ: الفرق التي هدفها الأساسي هو مستندات مرجعية لـ API ذات مظهر جيد وقابلة للصيانة.
swagger-cli، والذي لم يعد خيارًا حقًا
ستظل ترى swagger-cli مذكورًا في الأدلة القديمة، لذا من المهم أن نكون واضحين: swagger-cli مهملة. يقول مستودع swagger-cli على GitHub إنه لم يعد مدعومًا ويوجه المستخدمين إلى Redocly CLI كخلف له.
لم يكن يحتوي على أكثر من أمرين، swagger-cli validate و swagger-cli bundle. لم يقم أبدًا بالتدقيق بقواعد الأنماط، ولم يولد مستندات، ولم يشغل اختبارات، ولم يحاكي أي شيء. إذا كنت تستخدمه اليوم، فالانتقال هو الابتعاد عنه، لا استخدامه. يغطي دليلنا حول كيفية استخدام swagger-cli ما كان يفعله، وحتى Redocly تنشر دليل ترحيل من swagger-cli مع مطابقة الأعلام الدقيقة. سنقوم بتضمين هذه المطابقة أدناه للإكمال.
جدول المقارنة
إليك كيف تتوافق الخيارات مع المهام التي يتعامل معها Redocly CLI. "تدقيق القواعد المخصصة" يعني مدقق دليل أنماط قابل للتكوين ويعتمد على الكود أولاً مع مجموعات قواعد مخصصة.
| الأداة | تدقيق القواعد المخصصة | تجميع | توثيق | محاكاة | اختبار | واجهة رسومية للمستخدم (GUI) | مفتوح المصدر | الأفضل لـ |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | نعم | نعم | نعم (Redoc) | لا | لا | لا | نعم | حوكمة التدقيق والتجميع والتوثيق المعتمدة على الكود أولاً من الطرفية |
| Apidog | لا | عبر التصدير | نعم | نعم | نعم (مشغل CI) | نعم | لا (فريميوم) | منصة واحدة للتصميم، المحاكاة، الاختبار، والتوثيق |
| Spectral | نعم | لا | لا | لا | لا | لا | نعم | تدقيق OpenAPI/AsyncAPI نقي وقابل للتخصيص |
| Scalar / Bump.sh | لا | لا | نعم | لا | لا | نعم | يختلف | مستندات مرجعية لـ API مستضافة |
| swagger-cli | لا | نعم | لا | لا | لا | لا | نعم (مهملة) | لا جديد، لم تعد مدعومة |
ملاحظة حول الجدول: "عبر التصدير" في Apidog تعني أن apidog export يصدر ملفًا موحدًا واحدًا، وهذا يغطي السبب العملي لتشغيل redocly bundle، لكنه ليس أمر bundle مطابقًا تمامًا. و Apidog هو فريميوم، وليس مفتوح المصدر، بينما Redocly CLI و Spectral كلاهما مفتوح المصدر. سمِّ هذه المقايضات بما هي عليه.
مطابقة علامات التجميع من swagger-cli إلى Redocly CLI
إذا كنت تستخدم swagger-cli المهملة و Redocly هو وجهتك للتجميع، فإن الأعلام تتطابق بسلاسة:
| swagger-cli | Redocly CLI | المعنى |
|---|---|---|
-o, --outfile <file> |
--output (أو -o) |
الكتابة إلى ملف بدلاً من الإخراج القياسي (stdout) |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
نوع ملف الإخراج |
-r, --dereference |
-d, --dereferenced |
تضمين جميع مؤشرات $refs بالكامل |
لذلك، يصبح swagger-cli bundle -o output.json هو redocly bundle --output output.json.
توصية واضحة
لا يوجد فائز واحد، لأن الإجابة الصحيحة تعتمد على وظيفة Redocly CLI التي تحاول استبدالها.
احتفظ بـ Redocly CLI إذا كانت حوكمتها هي ما تحتاجه بالضبط. إن المدقق والمُجمِّع ومنشئ مستندات Redoc الخفيف والمفتوح المصدر والذي يعتمد على التكوين والذي تشغله بالكامل من الطرفية هو إعداد جيد حقًا. لا يوجد هنا سبب للتخلي عن أداة تناسب احتياجاتك.
اختر Apidog إذا كنت متعبًا من تجميع سلسلة أدوات وتريد تصميمًا ومحاكاة واختبارًا وتوثيقًا في منصة واحدة مع واجهة سطر أوامر (CLI) للأجزاء التي تتناسب مع الطرفية. ستتوقف عن صيانة أدوات منفصلة لكل مرحلة وستحصل على واجهة رسومية للمستخدم (GUI) للأشخاص في فريقك الذين يريدونها. كن واضحًا بأنك ستقرنه بـ Spectral إذا كنت تحتاج أيضًا إلى تدقيق بقواعد مخصصة. يوضح دليل Apidog CLI في CI/CD كيفية عمل مشغل الاختبار في خط أنابيب، ويقارن Apidog CLI مقابل Newman بينه وبين المشغل الذي تستخدمه العديد من الفرق بالفعل. يمكنك تنزيل Apidog وتجربته مجانًا، لا يلزم وجود بطاقة ائتمان.
اختر Spectral إذا كان التدقيق هو الهدف الرئيسي. لا تبدل المنصات لاستبدال أمر واحد.
التوضيح الصادق: Redocly هو متخصص في واجهة سطر الأوامر (CLI) يعتمد على الكود أولاً، و Apidog هو منصة مرئية شاملة. إنهما نموذجان مختلفان، وليسا استبدالًا مباشرًا. اختر ما يناسبك.
الأسئلة الشائعة
هل Apidog بديل مباشر لـ Redocly CLI؟ لا، ومن الأفضل أن نكون صريحين بشأن ذلك. يغطي Apidog المزيد من دورة الحياة (التصميم، المحاكاة، الاختبار، التوثيق) ولكنه لا يحتوي على مدقق قواعد مخصصة مثل redocly lint. إذا كانت حوكمة المواصفات الصارمة والقابلة للتكوين هي مهمتك الرئيسية، احتفظ بمدقق Redocly أو استخدم Spectral. يفوز Apidog عندما تريد أداة واحدة لدورة حياة API بأكملها بدلاً من عدة أدوات.
هل يحتوي Apidog CLI على أمر lint؟ لا. يتحقق Apidog من البنية عند استيراد المواصفات باستخدام apidog import، ولكن لا يوجد apidog lint ولا توجد طريقة لإنشاء قواعد مخصصة بأسلوب Spectral أو Redocly عبر واجهة سطر الأوامر (CLI). لذلك، قم بإقران Apidog بـ Spectral.
هل يمكنني تجميع ملف OpenAPI بدون Redocly CLI؟ نعم. يصدر apidog export --project <id> --format openapi --output ./openapi.json ملفًا موحدًا واحدًا ويمكنه استهداف إصدار OpenAPI معين باستخدام --oas-version. إنه ليس أمر bundle حرفيًا، لكنه يغطي نفس الحاجة العملية. إذا كنت تريد التجميع فقط ولا شيء آخر، فإن redocly bundle لا يزال خيارًا جيدًا ومركّزًا.
هل يجب علي استخدام swagger-cli في عام 2026؟ لا. swagger-cli مهملة وغير مدعومة، ويشير مستودعها الخاص إلى Redocly CLI كخلف لها. كانت تقوم فقط بالتحقق والتجميع. استخدم Redocly CLI لهذه المهمة، أو انتقل إلى منصة مثل Apidog إذا كنت تريد باقي دورة الحياة أيضًا.
ما الفرق بين هذا ومقارنة منصة مستندات Redocly؟ تتناول هذه المقالة أداة @redocly/cli مفتوحة المصدر: التدقيق، التجميع، التقسيم، الدمج، وبناء المستندات. إذا كنت تقارن منتج مستندات Redocly المستضاف أو Redoc كمحرك عرض للتوثيق، فاقرأ بدلاً من ذلك بدائل Redocly لتوثيق واجهة برمجة التطبيقات. يغطي الاثنان منتجات مختلفة تصادف أنها تشترك في الاسم. بالنسبة للمواصفات نفسها، فإن مواصفات OpenAPI هي مصدر الحقيقة، و Redocly CLI على npm هو المكان الذي ستجد فيه تفاصيل التثبيت الحالية.