مقارنة Apidog CLI و Redocly CLI: ما هو أفضل API CLI لك؟

كلا هاتين الأداتين تعملان في طرفيتك، وكلاهما يدعم OpenAPI، ويظهران عندما يقرر فريق ما أنه يريد سير عمل سطر أوامر لمواصفات واجهة برمجة التطبيقات الخاصة به. هذا هو المكان الذي ينتهي فيه التداخل. إنهما يحلان مشاكل متجاورة من اتجاهات متعاكسة، واختيار الأداة الخاطئة يعني إما مكافحة مدقق شيفرة لا يقوم بإجراء الاختبارات أو اللجوء إلى منصة بينما كل ما كنت تريده هو فحص هيكلي سريع.

هذه مقارنة مباشرة على مستوى الأوامر بين Apidog CLI و Redocly CLI. لا حجج واهية. إن Redocly CLI هو برنامج مفتوح المصدر جيد حقًا، وستعرف بالضبط أين يتألق قبل إصدار أي حكم.

الخلاصة (TL;DR)

إنهما يحلان مشاكل متداخلة ولكنها مختلفة.

Redocly CLI (@redocly/cli، الثنائي redocly) هو متخصص في OpenAPI يعتمد على الكود أولاً: يقوم بالتدقيق باستخدام مجموعات قواعد مخصصة، تجميع المواصفات متعددة الملفات، تقسيمها ودمجها، وبناء مستندات HTML مستقلة. إنه مفتوح المصدر، مدفوع بالتكوين، وأساسي للطرفية. إذا كانت مواصفاتك هي مصدر الحقيقة وتوجد في Git، فهذه هي الحوكمة التي تديرها من سطر الأوامر.

Apidog CLI (apidog-cli، الثنائي apidog) هي واجهة سطر الأوامر لمنصة API شاملة. تقوم باستيراد وتصدير التعريفات مقابل مشروع وتشغيل سيناريوهات اختبار API في CI مع تقارير JUnit و HTML. تثبت مكانتها عندما تحتاج المواصفات نفسها أيضًا إلى المحاكاة والاختبار والتوثيق في مساحة عمل واحدة بدلاً من تجميعها من أدوات منفصلة.

اختر Redocly CLI عندما تريد مدقق شيفرة ومجمع وباني مستندات خفيف الوزن ومفتوح المصدر تقوم بتشغيله بالكامل من الطرفية. اختر Apidog عندما تفضل الحصول على أداة واحدة لدورة حياة API بأكملها. يمكنهما العمل جنبًا إلى جنب أيضًا، ويشرح القسم الأخير كيف.

فلسفتان مختلفتان

Redocly CLI يركز على الملفات ويعتمد على الكود أولاً. مستند OpenAPI على القرص هو الشيء الذي تتفاعل معه. كل أمر، مثل redocly lint، redocly bundle، redocly build-docs، يأخذ مسارًا إلى ملف ويقوم بعمله محليًا، بدون حساب ولا خادم في الدورة. يتم تحديد السلوك بواسطة ملف تكوين redocly.yaml الذي تقوم بتضمينه في المستودع بجانب المواصفات. يناسب هذا النموذج الفرق التي تتعامل مع وصف API الخاص بها كشفرة مصدر: يتم مراجعته في طلبات السحب، ويتم فحصه في CI، ويتم التحكم في إصداراته مثل أي شيء آخر. مواصفات OpenAPI هي العقد، و Redocly CLI هي مجموعة الأدوات التي تتحكم فيه.

Apidog يركز على المشاريع ويعتمد على المنصة أولاً. يمكنك تصميم نقاط النهاية، وبناء خوادم وهمية، وتأليف سيناريوهات الاختبار بصريًا في تطبيق سطح المكتب أو الويب، والواجهة السطرية (CLI) هي الواجهة الخلفية لجزء من هذا العمل. تعمل معظم أوامر CLI مقابل مشروع Apidog على الخادم، ويتم تحديدها بواسطة معرف المشروع والمصادقة باستخدام رمز وصول. المواصفات ليست ملفًا غير مقيد تقوم بتدقيقه في مكانه؛ بل يتم استيرادها إلى مساحة عمل حية حيث يمكن أيضًا محاكاتها واختبارها ونشرها كمستندات. بيئة واحدة، وظائف متعددة.

لا توجد فلسفة خاطئة. إنهما يناسبان فرقًا مختلفة. التمييز الصادق هو هذا: Redocly يوفر لك واجهة سطر أوامر (CLI) مركزة ومفتوحة المصدر لحوكمة المواصفات، بينما Apidog يوفر لك واجهة سطر أوامر (CLI) لمنصة أوسع.

أمر بأمر

هذا هو الجزء المهم، يتم عرضه مهمة بمهمة. كل أمر أدناه حقيقي؛ لا شيء مختلق.

تستحق بعض هذه الصفوف ملاحظة صريحة، لأن الفرق حقيقي وسيكون المقال غير أمين بدونه.

التدقيق هو ملعب Redocly الخاص، وليس Apidog. يقوم Redocly CLI بتدقيق OpenAPI و AsyncAPI و Arazzo و Open-RPC مقابل مجموعات قواعد قابلة للتكوين، ويمكنك تأليف قواعدك الخاصة. يتحقق Apidog من بنية التعريف عند استيراده، ولكن لا يوجد أمر apidog lint، ولا تكوين على غرار redocly.yaml، ولا توجد طريقة لكتابة قواعد دليل الأسلوب المخصصة عبر CLI. إذا كان هدفك هو دليل أسلوب يعتمد على الكود أولاً ويتم فرضه في الطرفية، فإن Redocly هي الأداة. Apidog لا ينافس هنا، وقول غير ذلك سيكون خاطئًا.

التقسيم والدمج ملك Redocly. يقوم redocly split بتحويل وصف واحد إلى بنية متعددة الملفات، و redocly join (تجريبي) يدمج عدة ملفات في ملف واحد. Apidog لا يمتلك أيًا من هذين الأمرين. يحل استيراده مراجع $ref متعددة الملفات إلى موارد موحدة، ويصدر ملفًا موحدًا واحدًا، لكن هذا ليس مثل أداة تقسيم/دمج مستقلة تشغلها على ملفات متفرقة.

تشغيل الاختبارات والمحاكاة (Mocking) تخص Apidog. لا يقوم Redocly CLI بتنفيذ اختبارات API ولا يستضيف خادمًا وهميًا؛ وهذا خارج نطاق عمله بالتصميم. يشغل Apidog سيناريوهات الاختبار بدون واجهة مستخدم رسومية باستخدام apidog run وينتج تقارير JUnit و HTML و JSON و CLI لخط أنابيبك، والمحاكاة هي ميزة أساسية للمنصة (يتم تأليفها في التطبيق، ولا يتم التحكم فيها من CLI).

كلاهما يبني مستندات HTML من الطرفية. ينتج redocly build-docs ملف Redoc HTML مستقلاً. يكتب apidog export --format html ملف مستندات HTML من مشروعك. محركات مختلفة، نفس النتيجة في الطرفية.

أوامر Redocly CLI الفعلية

قم بتثبيته عالميًا، أو تخطى التثبيت وقم بتشغيله عبر npx:

npm install -g @redocly/cli@latest
# أو، بدون تثبيت عام:
npx @redocly/cli@latest lint openapi.yaml

قم بتدقيق المواصفات. مع وجود redocly.yaml، يطبق هذا الأمر مجموعة القواعد التي اخترتها (minimal، recommended، recommended-strict، spec، أو قواعد مخصصة):

redocly lint openapi.yaml

إذا كنت تريد فقط التحقق الهيكلي البسيط، من النوع الذي كان يقوم به swagger-cli المهمل، قم بتكوين redocly.yaml باستخدام قاعدة spec فقط وقم بتشغيل نفس redocly lint. تنشر Redocly دليل ترحيل من swagger-cli لأن Redocly CLI هو خليفته المسمى. يحمل مستودع swagger-cli الآن إشعار إهمال لنفس السبب؛ فهذه الأداة القديمة كانت تتحقق وتجمع فقط، ولم تقم أبدًا بالتدقيق باستخدام قواعد الأسلوب.

قم بتجميع تعريف متعدد الملفات في ملف واحد، مع تتبع كل $ref:

redocly bundle openapi.yaml --output bundled.json

إذا كنت قادمًا من swagger-cli، فإن العلامات تتطابق بسلاسة: يصبح -o/--outfile هو --output، ويصبح -t/--type هو --ext (json، yaml، أو yml)، ويصبح -r/--dereference هو -d/--dereferenced.

بناء مستندات HTML مستقلة باستخدام Redoc:

redocly build-docs openapi.yaml -o docs.html

تقسيم وصف واحد إلى تخطيط متعدد الملفات، وهو عكس التجميع:

redocly split openapi.yaml --outDir ./split-spec

لإلقاء نظرة أوسع على كيفية مقارنة Redocly بالأدوات الأخرى في هذه الفئة، يغطي دليل إعداد OpenAPI linter أدوات Spectral و Redocly و Vacuum جنبًا إلى جنب، ويغطي ملخص بدائل Redocly منصة المستندات على وجه التحديد.

أوامر Apidog CLI الفعلية

قم بتثبيت CLI والمصادقة باستخدام رمز (توكن) من التطبيق (الصورة الرمزية، ثم إعدادات الحساب، ثم رمز الوصول إلى API):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

يتم حفظ الرمز في ~/.apidog/config.toml. لا تطبعه أو تلتزم به في المستودع.

استورد تعريفًا إلى مشروع. هذا يتحقق من البنية ويستوعبها، ويحل مراجع $ref متعددة الملفات إلى موارد موحدة:

apidog import --project 123456 --format openapi --file ./openapi.json

يقبل الاستيراد أكثر من OpenAPI: Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema، وتنسيق Apidog الخاص.

صدر ملفًا موحدًا واحدًا، مع ترقية اختيارية لإصدار OpenAPI. هذا هو التجميع بالإضافة إلى ترقية إصدار اختيارية في خطوة واحدة:

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 run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

يمكنك أيضًا التشغيل بالكامل دون اتصال بالإنترنت من ملف مجموعة تم تصديره، لا حاجة لمشروع أو رمز:

apidog run ./collection.apidog-cli.json

المرجع الكامل للعلامات، بما في ذلك --out-dir، -n/--iteration-count، -d/--iteration-data، و --env-var، موجود في دليل Apidog CLI الشامل. تغطي وثائق Apidog CLI الرسمية التثبيت وكل أمر للموارد. لإجراء مقارنة CI بين المشغلات، انظر Apidog CLI مقابل Newman و Bruno CLI مقابل Apidog CLI.

متى تختار Redocly CLI

الجا إلى Redocly CLI عندما تكون المواصفات هي مصدر الحقيقة الخاص بك وترغب في إدارتها كشفرة.

تريد مدقق شيفرة حقيقيًا بقواعد مخصصة. أمر lint الخاص بـ Redocly وملف التكوين redocly.yaml هما الميزة المميزة: اختر مجموعة قواعد مدمجة أو اكتب مجموعتك الخاصة، وافرض اتفاقيات التسمية والحقول المطلوبة ونمط الشركة في كل التزام. لا شيء في Apidog CLI يطابق هذا. إذا كانت حوكمة الأسلوب الأصيلة في الطرفية هي المهمة، فإن Redocly هو الحل.

تريد مصدرًا مفتوحًا بدون حساب. يعمل CLI بالكامل على جهازك أو مشغل CI. لا يوجد تسجيل دخول، ولا رمز (توكن)، ولا استدعاء للخادم لأوامر lint، bundle، split، أو build-docs. بالنسبة للبيئات المعزولة جويًا أو قواعد معالجة البيانات الصارمة، هذا متطلب صعب يلبيه Redocly ولا تلبي منصة CLI ذلك بشكل عام.

تريد مجموعة أدوات خفيفة الوزن ومركزة. إذا كان كل ما تحتاجه هو التدقيق والتجميع والتقسيم والدمج ومستندات HTML من الطرفية، فإن Redocly يقوم بذلك بالضبط ولا شيء أكثر. يمكنك تثبيته أو تشغيله عبر npx بدون أي إعداد. مجموعة الأوامر الكاملة موجودة في وثائق Redocly CLI و صفحة حزمة npm.

متى تختار Apidog

الجا إلى Apidog عندما تكون المواصفات جزءًا واحدًا من دورة حياة أكبر تفضل عدم تجميعها من أدوات منفصلة.

تريد التصميم والمحاكاة والاختبار والوثائق في مكان واحد. تقوم CLI باستيراد مواصفاتك، وتصدير ملف موحد نظيف بالإصدار الذي تختاره من OpenAPI، وتشغيل سيناريوهات الاختبار في CI. يوفر لك نفس المشروع أيضًا تصميمًا مرئيًا، وخادمًا وهميًا، ووثائق منشورة، وكلها تشترك في تعريف واحد. تتوقف عن تجميع مدقق شيفرة وأداة محاكاة ومُشغل اختبار ومولد وثائق.

تريد تنفيذ الاختبارات في خط أنابيبك بتقارير قابلة للاستخدام. ينتج apidog run ملفات JUnit XML للوحة تحكم CI الخاصة بك، بالإضافة إلى عناصر HTML و JSON، ويخرج بقيمة غير صفرية عند فشل الاختبار. لا يقوم Redocly بتشغيل الاختبارات على الإطلاق، لذا إذا كان فحص الاختبار في CI ضمن قائمة متطلباتك، فهنا يأتي دور Apidog. تتطابق الأنماط في التحقق من صحة OpenAPI في CI بشكل طبيعي مع تشغيل الاختبار على نفس خط الأنابيب.

تريد مصدر حقيقة واحدًا لفريق بأكمله. توجد الموارد في مشروع Apidog يعمل منه المصممون والمختبرون والكتاب جميعًا. الواجهة السطرية (CLI) هي واجهة الأتمتة فوق مساحة العمل المشتركة تلك، والتي تناسب الفرق التي تفضل التعاون في منصة بدلاً من تمرير ملفات المواصفات.

قم بتنزيل Apidog للمتابعة. إنه مجاني للبدء، ولا يتطلب بطاقة ائتمان.

يمكن أن يكونا مكملين لبعضهما

هذا ليس إما/أو بالضرورة، والتظاهر بخلاف ذلك سيفوت التكوين الأكثر عملية.

يشغل سير عمل قوي Redocly CLI (أو Spectral) كبوابة تدقيق في CI، ويفرض دليل الأسلوب الخاص بك على كل طلب سحب، ويستخدم Apidog للتصميم والمحاكاة وتنفيذ الاختبارات والوثائق المنشورة. قم بالتدقيق حيث يكون التدقيق أفضل، باستخدام مجموعات قواعد مفتوحة المصدر في الطرفية. قم بالمحاكاة والاختبار والتوثيق حيث تكون المنصة هي الأفضل. تتدفق المواصفات بينهما: قم بتدقيق الملف في CI، ثم استورده إلى Apidog لكل شيء لاحق.

يستغل هذا المزيج القوة الحقيقية لكل أداة بدلاً من إجبار إحداهما على القيام بعمل الأخرى.

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

هل يمتلك Apidog CLI أمر تدقيق (lint) بقواعد مخصصة مثل Redocly؟

لا. يتحقق Apidog من بنية التعريف عند استيراده، ولكن لا يوجد أمر apidog lint ولا توجد طريقة لتأليف قواعد دليل الأسلوب المخصصة عبر CLI. للتدقيق القابل للتكوين والذي يعتمد على الكود أولاً، استخدم Redocly CLI أو Spectral.

هل يمكن لـ Redocly CLI تشغيل اختبارات API في CI؟

لا. يقوم Redocly CLI بالتدقيق، التجميع، التقسيم، الدمج، وبناء الوثائق. لا ينفذ اختبارات API ولا يستضيف خادمًا وهميًا. لتشغيل الاختبارات بدون واجهة مستخدم رسومية مع تقارير JUnit و HTML، استخدم apidog run.

هل Apidog مفتوح المصدر مثل Redocly CLI؟

لا. Redocly CLI و Spectral مفتوحان المصدر. Apidog يعتمد على نموذج أعمال فريميوم: CLI مجاني للتثبيت من npm، ولكنه يعمل مقابل حساب ومشروع Apidog بدلاً من كونه برنامجًا مفتوح المصدر بالكامل.

لقد استخدمت swagger-cli للتحقق والتجميع. إلى ماذا يجب أن أنتقل؟

كلا الأداتين تغطيان ذلك. Redocly CLI هو خليفة swagger-cli المسمى، مع redocly lint (قم بتكوين قاعدة spec للتحقق البسيط) و redocly bundle. يغطي Apidog نفس النطاق من خلال apidog import (للتحقق) و apidog export (للتجميع، مع ترقية اختيارية لإصدار OpenAPI)، ويضيف المحاكاة والاختبار والوثائق في نفس مساحة العمل.