DEV Community

Cover image for أفضل أدوات CLI خفيفة الوزن للتعاون في واجهات برمجة التطبيقات
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

أفضل أدوات CLI خفيفة الوزن للتعاون في واجهات برمجة التطبيقات

كان التعاون في واجهة برمجة التطبيقات (API) يعني سابقًا فتح تطبيق ثقيل، وانتظار المزامنة، ثم التنقل بين اللوحات لمعرفة ما غيّره أحد الزملاء. لم تعد بحاجة إلى ذلك. عندما تكون واجهة برمجة التطبيقات موصوفة بملف OpenAPI، يصبح معظم التعاون عملًا نصيًا: تحديد إصدار المواصفات، ومراجعة الفروقات، ودمج التغييرات. وكل ذلك يمكن إنجازه من سطر الأوامر.

جرّب Apidog اليوم

يغطي هذا الدليل أدوات CLI خفيفة لتنفيذ المهام الثلاث: تحديد إصدارات المواصفات، مراجعة التغييرات، ودمج العمل المشترك. يمكن تثبيت كل أداة بسرعة وتشغيلها بأمر واحد ودمجها مع Git أو CI. لا تحتاج إلى واجهة رسومية أو خدمات تعمل باستمرار. للحصول على نظرة أوسع على سير عمل الفرق، راجع أدوات التعاون في واجهة برمجة التطبيقات؛ أما هذه المقالة فتركز على أدوات سطر الأوامر.

الإطار العملي بسيط:

  1. تحديد الإصدار: ما النسخة المعتمدة من المواصفات؟
  2. المراجعة: ما الذي تغيّر؟ وهل يكسر العملاء الحاليين؟
  3. الدمج: كيف يصل التغيير الموافق عليه إلى مصدر الحقيقة المشترك؟

تقرأ الأدوات التالية مواصفات OpenAPI، وهو المعيار المشترك الذي يجعل هذا التدفق ممكنًا.

ما الذي يجعل أداة سطر الأوامر خفيفة الوزن للتعاون في API؟

ليست “خفيفة الوزن” مجرد وصف تسويقي. غالبًا ما تستوفي الأداة الخفيفة معظم المعايير التالية:

  • تثبيت بسيط: ملف ثنائي واحد، أو npx، أو أمر npm install -g.
  • تشغيل سريع: تنفذ المهمة ثم تنتهي، لذا تصلح للنصوص البرمجية وخطافات Git وCI.
  • إعداد محدود: تعمل مباشرةً على ملف مثل openapi.yaml.
  • موجهة للطرفية: يمكن قراءة مخرجاتها في terminal أو تمريرها إلى CI.
  • محددة الوظيفة: تقارن أو تدقق أو تنشر أو تدمج، بدل فرض منصة كاملة.

ابدأ بأبسط مكدس ممكن، ثم أضف أداة فقط عندما تظهر حاجة واضحة: فرق دلالي، بوابة للتغييرات الكاسرة، نشر وثائق، أو إدارة فروع ومراجعات.

Git + ملف المواصفات: الأساس

أخف أداة تعاون هي غالبًا موجودة لديك بالفعل: Git.

ضع ملف OpenAPI بجوار الكود في المستودع. عندها تحصل تلقائيًا على سجل التغييرات، والمراجعات، وطلبات السحب، والدمج. هذه هي الفكرة وراء التعاون الأصلي في واجهة برمجة التطبيقات عبر Git.

# أضف المواصفات إلى المستودع وراجع التغييرات كما تراجع الكود
git add openapi.yaml
git commit -m "إضافة معاملات التصفح إلى GET /orders"
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

متى تستخدمه؟

استخدم Git عندما تحتاج إلى:

  • سجل واضح لكل تعديل.
  • مراجعة تغييرات المواصفات داخل Pull Request.
  • دمج المواصفات مع دورة مراجعة الكود الحالية.

الحد العملي

فرق Git النصي على YAML قد يكون صاخبًا. إعادة ترتيب المفاتيح أو تغيير المسافات البادئة قد يظهر كتغيير كبير رغم عدم تغير سلوك API. لذلك أضف أداة diff دلالية مثل oasdiff أو Optic.

oasdiff: بوابة للتغييرات الكاسرة

oasdiff أداة مبنية بلغة Go تقارن مواصفتي OpenAPI وتحدد إن كان التغيير كاسرًا للعملاء الحاليين. وهي مفتوحة المصدر بترخيص Apache 2.0.

استخدمها في CI لمنع دمج تغيير كاسر قبل وصوله إلى الفرع الرئيسي.

# التثبيت على macOS
brew install oasdiff

# يفشل الأمر إذا كانت المواصفات الجديدة تكسر العملاء الحاليين
oasdiff breaking main-spec.yaml pr-spec.yaml

# exit code 0: لا توجد تغييرات كاسرة
# exit code 1: تم العثور على تغييرات كاسرة
Enter fullscreen mode Exit fullscreen mode

لإنشاء ملخص كامل للتغييرات، وليس فقط التغييرات الكاسرة:

oasdiff changelog main-spec.yaml pr-spec.yaml
Enter fullscreen mode Exit fullscreen mode

مثال في CI 

oasdiff breaking openapi/main.yaml openapi/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

إذا أعاد الأمر رمز خروج غير صفري، أوقف الدمج واطلب من صاحب التغيير إما الحفاظ على التوافق أو توثيق كسر الإصدار.

الأفضل لـ: بوابة دمج للتغييرات الكاسرة.

الحد: يقارن ويبلغ فقط؛ لا يدير فروعًا أو ينشر وثائق.

Optic: مراجعة تغييرات OpenAPI داخل PR

Optic هي أداة CLI مثبتة عبر npm لمقارنة وتدقيق ومراجعة تغييرات OpenAPI ضمن سير عمل Git. تفهم تراكيب مثل $ref وoneOf وallOf، وهي تراكيب قد تجعل الفروقات النصية البسيطة غير مفيدة.

# التثبيت
npm install -g @useoptic/optic

# قارن المواصفات الحالية بما هو موجود في الفرع الرئيسي
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

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

تدفق مقترح

  1. أنشئ فرعًا لتعديل المواصفات.
  2. عدّل openapi.yaml.
  3. شغّل optic diff مقابل main.
  4. أضف الأمر إلى CI قبل السماح بالدمج.

الأفضل لـ: مراجعة تغييرات منظمة داخل PRs.

الحد: تتطلب Node، وتزداد فائدتها عند اعتماد قواعدها وإعداداتها.

Bump.sh CLI: نشر الوثائق ومقارنة الإصدارات

تستخدم Bump.sh CLI لنشر وثائق API ومقارنة ملفك المحلي بالإصدار المنشور. هنا يكون التعاون حول وثيقة مشتركة ومحدثة يقرأها الفريق والمستهلكون.

# التثبيت
npm install -g bump-cli

# نشر نسخة جديدة من الوثائق المشتركة
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# عرض الفرق بين ملفك المحلي والإصدار المنشور
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

يمكنك إدراج ناتج bump diff في تعليق Pull Request حتى يراجع الفريق أثر التغيير قبل النشر.

الأفضل لـ: نشر وثائق مشتركة مع فروقات قابلة للقراءة.

الحد: الوثائق المستضافة وسير عمل النشر جزء من منتج Bump.sh المدفوع. تتطلب الحزمة Node 20+، بينما يمكن تشغيل diff وpreview دون رمز مميز.

Redocly CLI: التدقيق والتجميع والسجل المشترك

Redocly CLI مجموعة أدوات لـ OpenAPI تدعم التدقيق والتجميع ودفع المواصفات إلى سجل Redocly.

استخدم lint لتطبيق قواعد الجودة، وbundle لتحويل مواصفات متعددة الملفات إلى ملف واحد قابل للنشر أو المشاركة.

# لا تحتاج إلى تثبيت عام
npx @redocly/cli lint openapi.yaml

# اجمع ملفات OpenAPI والمراجع $ref في ملف واحد
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

بعد التحقق والتجميع، ادفع النسخة إلى سجل مشترك:

# يتطلب مفتاح API
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

تدفق عملي 

npx @redocly/cli lint openapi.yaml \
  && npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml \
  && npx @redocly/cli push dist/openapi.yaml --organization "Acme" --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

الأفضل لـ: التدقيق بأسلوب داخلي وتجميع المواصفات متعددة الملفات ودفعها إلى سجل مشترك.

الحد: lint وbundle محليان، لكن push والسجل جزء من منصة Redocly المستضافة. لمزيد من العمل على تحرير المواصفات، راجع التحرير التعاوني لمواصفات API.

GitHub CLI (gh): إدارة PR من الطرفية

إذا كان فريقك يستخدم GitHub، فـ GitHub CLI يجلب دورة Pull Request إلى الطرفية: إنشاء PR، طلب مراجعين، التحقق من الحالة، والموافقة.

# أنشئ طلب سحب لتغيير المواصفات
gh pr create \
  --title "إضافة تصفح لـ /orders" \
  --body "يضيف معاملات الصفحة والحد"

# وافق على طلب السحب
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

لأفضل نتيجة، اربطه بأداة دلالية مثل oasdiff أو Optic:

oasdiff breaking main-spec.yaml openapi.yaml && gh pr create \
  --title "تحديث مواصفات Orders API" \
  --body "تم التحقق من عدم وجود تغييرات كاسرة."
Enter fullscreen mode Exit fullscreen mode

الأفضل لـ: إدارة محادثة المراجعة والدمج من الطرفية.

الحد: لا يفهم دلالات OpenAPI ولا يحدد ما إذا كان التغيير كاسرًا.

Apidog CLI: الفروع والمراجعة والدمج في مكان واحد

Apidog CLI ليس أداة أحادية الغرض؛ بل واجهة سطر أوامر لموارد المشروع الكاملة في Apidog. يركز التعاون فيه على ثلاث مجموعات أوامر:

  • branch
  • merge-request
  • git-connection

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

1. تثبيت CLI والمصادقة 

npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

2. إنشاء فرع معزول

اختر نوع الفرع عبر --type:

  • sprint لميزة أو إصدار محدد.
  • general للعمل المستمر.
  • ai لفرع معزول يعدّل فيه وكيل الموارد دون لمس المصدر الأساسي. 
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

3. فتح طلب دمج للمراجعة

بدل الدمج المباشر، أنشئ طلب دمج يمر عبر المراجعة، خصوصًا عند حماية الفرع الرئيسي.

apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

تحدد --endpoint-ids الموارد المشمولة في التغيير، ما يحافظ على نطاق الدمج واضحًا ومحدودًا.

4. ربط المواصفات بمستودع Git

يمكن لـ git-connection دعم ملف OpenAPI لكل وحدة داخل مستودع Git، بما يشمل GitHub وGitLab وAzure DevOps.

apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

تنتج الأوامر JSON منظمًا يتضمن agentHints.nextSteps، ما يجعلها مناسبة للنصوص البرمجية ووكلاء الذكاء الاصطناعي. للمزيد، راجع الدليل الكامل لـ Apidog CLI.

الأفضل لـ: سير عمل موحد لتحديد الإصدار والمراجعة والدمج، مع نماذج فروع للفرق والوكلاء.

الحد: تتصل بمشروع Apidog بدل ملف محلي فقط، ولا توفر مدققًا لغويًا لـ OpenAPI؛ استخدم Redocly أو Spectral لقواعد الأنماط. إذا احتجت تحكمًا قائمًا على الأدوار، راجع التعاون الآمن في واجهة برمجة التطبيقات مع RBAC.

كيف تختار؟

طابق الأداة مع مهمة التعاون المطلوبة:

الأداة الأفضل لـ التثبيت مفتوح المصدر؟ ملاحظات
Git + ملف المواصفات السجل والمراجعة دون أدوات إضافية مثبت بالفعل نعم، Git فروقات YAML صاخبة؛ أضف diff دلاليًا
oasdiff منع دمج التغييرات الكاسرة brew install oasdiff نعم، Apache 2.0 رمز الخروج مناسب لـ CI
Optic مراجعة تغييرات منظمة في PRs npm i -g @useoptic/optic نعم، MIT يفهم $ref وoneOf وallOf
Bump.sh CLI نشر الوثائق المشتركة والفروقات npm i -g bump-cli CLI مفتوح، الاستضافة مدفوعة Node 20+
Redocly CLI التدقيق والتجميع والدفع للسجل npx @redocly/cli CLI مفتوح، السجل مدفوع push يحتاج مفتاح API
GitHub CLI إدارة مراجعات PR من الطرفية brew install gh نعم، MIT يدير PR ولا يفهم دلالات API
Apidog CLI تحديد الإصدار والمراجعة والدمج npm i -g apidog-cli لا، طبقة مجانية branch وmerge-request وgit-connection

مكدسات عملية مقترحة

مكدس بسيط لفريق يستخدم GitHub 

# 1. راجع التغييرات الدلالية
oasdiff breaking main-spec.yaml openapi.yaml

# 2. أنشئ PR من الطرفية
gh pr create --title "تحديث OpenAPI" --body "تم التحقق عبر oasdiff."
Enter fullscreen mode Exit fullscreen mode

مكدس للنشر بعد نجاح CI 

# 1. تحقق من الجودة
npx @redocly/cli lint openapi.yaml

# 2. امنع التغييرات الكاسرة
oasdiff breaking main-spec.yaml openapi.yaml

# 3. انشر الوثائق
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN
Enter fullscreen mode Exit fullscreen mode

مكدس موحد للفروع والمراجعة 

apidog branch create --type sprint --name "orders-pagination"

# نفّذ التعديلات المطلوبة في الفرع

apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

تنتهي معظم الفرق باستخدام عدة أدوات معًا: Git للسجل، وoasdiff أو Optic كبوابة دمج، وBump.sh أو Redocly لنشر الوثائق. وإذا كنت تفضل تشغيل الفروع والمراجعة والدمج من CLI واحد، فإن Apidog يغطي هذه الأجزاء. للمقارنة بين المكدسات، راجع أدوات تعاون فريق API.

خاتمة

يتكون التعاون على OpenAPI من الطرفية من ثلاث خطوات:

  1. تحديد إصدار المواصفات.
  2. مراجعة الفروقات والتغييرات الكاسرة.
  3. دمج التغيير ونشر المصدر المشترك.

استخدم Git كأساس. أضف oasdiff أو Optic للتحقق الدلالي. استخدم Redocly أو Bump.sh عندما تحتاج إلى وثائق أو سجل مشترك. واستخدم gh لإدارة مراجعات Pull Request دون مغادرة الطرفية.

إذا كنت تريد مسارًا متكاملًا دون تجميع أدوات منفصلة، نزّل Apidog، وثبّت apidog-cli، ثم أنشئ أول فرع عبر apidog branch create وافتح طلب دمج من الطرفية التي تستخدمها بالفعل.

Top comments (0)