DEV Community: Yusuf Khalidd

كيفية منع وكلاء الذكاء الاصطناعي من تعطيل واجهات برمجة التطبيقات العاملة

Yusuf Khalidd — Tue, 14 Jul 2026 03:48:33 +0000

امنح وكيل الذكاء الاصطناعي صلاحية الكتابة إلى مشروع API، وقد يتسبب في ضرر حقيقي دون قصد. الوكيل ينفذ ما يطلبه الموجه: قد يزيل مسارًا مباشرًا عند طلب «تنظيف نقاط نهاية المستخدم»، أو يستبدل مخطط بيانات تعتمد عليه نقاط نهاية أخرى عند طلب «تحديث المخطط». لا يعرف الوكيل ما هو منشور في الإنتاج؛ بل يرى الموارد التي تسمح له بالوصول إليها ويعدّلها.

جرّب Apidog اليوم

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

الحل ليس منع الوكلاء، بل وضعهم في بيئة معزولة لا يمكنهم الخروج منها. يوفّر فرع الذكاء الاصطناعي (AI Branch) في Apidog هذا العزل: كل تعديل ينفذه الوكيل يهبط في فرع منفصل، بينما يبقى الفرع المصدر سليمًا، ولا يصل شيء إلى main قبل مراجعته ودمجه بواسطة إنسان.

للاطلاع على منطق التصميم، اقرأ مقال فرع الذكاء الاصطناعي وتغييرات الوكلاء الأكثر أمانًا. أما هنا، فستطبق سير عمل CLI عمليًا من البداية إلى النهاية.

لماذا يكون وصول الوكيل للكتابة خطيرًا افتراضيًا؟

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

اقتراح الوكيل لتغيير.
وصول هذا التغيير إلى مصدر الحقيقة.

تظهر عادةً ثلاثة أنماط للفشل:

الكتابة فوق الموارد: يعيد الوكيل إنشاء مخطط من فهم جزئي للـ API، فيسقط حقولًا تحتاجها نقاط نهاية أخرى.
الحذف غير المقصود: «يدمج» الوكيل نقاط النهاية ويحذف مسارات ما زال العملاء المباشرون يستدعونها.
الانجراف الصامت: ينفذ الوكيل عشرات التعديلات الصغيرة في جلسة واحدة. قد يبدو كل تعديل سليمًا بمفرده، لكن النتيجة النهائية تنحرف عن الإصدار المنشور.

هذه ليست حالات استثنائية؛ إنها نتيجة طبيعية لوكيل يعمل على الفرع الخطأ. لذلك يجب أن تجعل الوصول إلى الفرع الخطأ مستحيلًا.

الحل: إنشاء فرع AI معزول

فرع الذكاء الاصطناعي هو نوع خاص من فروع Sprint مخصص لعمليات الذكاء الاصطناعي الخارجية وواجهة سطر الأوامر. ينفذ الوكيل تعديلاته داخل هذا الفرع فقط، ولا يتأثر الفرع المصدر أو main حتى تقرر أنت الدمج.

1. ثبّت Apidog CLI وسجّل الدخول

ثبّت Apidog CLI، ثم صادق باستخدام رمز وصول:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

استخدم رمز وصول مخصصًا للوكيل وبأقل الصلاحيات الممكنة، بدلًا من استخدام رمز المالك الشخصي.

2. أنشئ فرع AI من `main`

استخدم اسمًا يوضح التاريخ والفرع المصدر والغرض من المهمة:

apidog branch create --type ai \
  --name "ai/20260708-from-main-user-register" \
  --from main \
  --project <PROJECT_ID>

نقطتان مهمتان:

يتم إنشاء الفرع انطلاقًا من main، لكن هذا لا يعدّل main.
يبدأ فرع AI فارغًا؛ فهو لا ينسخ المشروع كاملًا تلقائيًا.

هذه خاصية أمان مقصودة: الوكيل لا يستطيع تعديل سوى الموارد التي تستوردها إليه صراحةً، وبالتالي يصبح نطاق التغيير محددًا بدلًا من أن يشمل المشروع كله.

لعرض جميع خيارات أوامر الفروع:

apidog branch create -h

استورد الموارد المطلوبة فقط

بما أن فرع AI يبدأ فارغًا، يجب أن تستورد إليه الموارد التي سيعمل عليها الوكيل. لا تستورد المشروع كاملًا لمجرد الراحة؛ اجلب فقط نقاط النهاية والمخططات والمستندات المرتبطة بالمهمة.

على سبيل المثال، لاستيراد نقطتي نهاية ومخطط بيانات من main:

apidog branch pick-to \
  --type ai \
  --from main \
  --to "ai/20260708-from-main-user-register" \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

الآن يحتوي فرع AI على نسخة من:

نقطتي النهاية 1 و2
مخطط البيانات 3

يعمل الوكيل على هذه النسخ فقط. إذا حذف نقطة نهاية داخل فرع AI، فإنه يحذف النسخة المؤقتة لا المسار المباشر على main.

عند تشغيل الأوامر من داخل وكيل برمجي، يعيد Apidog CLI مخرجات JSON منظمة، بما في ذلك agentHints.nextSteps. يمكن للوكيل استخدام هذه البيانات لتحديد الخطوة التالية دون تحليل نص الإخراج يدويًا.

لرؤية هذا النمط ضمن محرر فعلي، راجع دليل apidog-cli في Cursor.

نفّذ التعديلات داخل الفرع ثم راجع الفروقات

بعد استيراد الموارد، دع الوكيل ينفذ مهمته داخل فرع AI. يمكنه إنشاء أو تحديث أو حذف:

نقاط النهاية
مخططات البيانات
المستندات
سيناريوهات الاختبار

كل عمليات الكتابة تظل محتواة داخل الفرع المعزول.

عند انتهاء الوكيل، راجع الفروقات قبل دمج أي شيء. يمكنك إجراء المراجعة عبر CLI أو عميل Apidog. تعامل مع هذه الخطوة كبوابة إلزامية:

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

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

أرسل التغييرات عبر طلب دمج

تعتمد طريقة الدمج على حالة حماية الفرع المستهدف.

الدمج المباشر إلى فرع غير محمي

إذا لم يكن الفرع المستهدف محميًا، يمكنك دمج الموارد المحددة مباشرة:

apidog branch merge \
  --type ai \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

لكن لا تجعل هذا الخيار هو القاعدة للنتائج التي ينشئها الوكيل.

إنشاء طلب دمج إلى `main` محمي

إذا كان main محميًا — وهو الإعداد الموصى به — فلن يكون الدمج المباشر متاحًا. أنشئ طلب دمج بدلًا من ذلك:

apidog merge-request create \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --reviewer-ids <REVIEWER_USER_IDS> \
  --description "AI branch: user register changes" \
  --project <PROJECT_ID>

هذا هو المسار المفضل لأي تغيير يولده وكيل، لأنه يفرض نفس دورة العمل المتبعة مع المساهمين البشر:

إنشاء فرع.
اقتراح تغيير.
مراجعة من زميل.
الموافقة والدمج.

لا يكتب الوكيل إلى main مباشرة؛ بل يطلب دمج العمل الذي أنجزه. كذلك، لا يُدمج إلا ما تحدده بالمعرّفات. إذا لمس الوكيل موردًا لا تريد شحنه، استبعد معرّفه من أمر الدمج وسيبقى داخل الفرع المعزول.

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

نظّف الفروع المدمجة أو المهجورة

استخدم فرع AI واحدًا لكل مهمة. بعد دمج المهمة أو إلغائها، أرشف الفرع فورًا:

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>

هذا الإيقاع يحافظ على وضوح قائمة الفروع:

مهمة واحدة لكل فرع.
مراجعة واحدة لكل مجموعة تغييرات مترابطة.
دمج أو رفض واضح.
أرشفة بعد الانتهاء.

لا تترك فرعًا واحدًا يتراكم فيه عمل عدة جلسات غير مرتبطة؛ لأن ذلك يجعل المراجعة أصعب ويضعف فائدة العزل.

قواعد أمان إضافية للوكلاء

فرع AI يعالج العزل، لكنه يصبح أكثر فاعلية عند تطبيق هذه القواعد حوله.

استخدم رموز وصول بأقل الامتيازات

رمز الوصول الذي تمرره إلى:

apidog login --with-token <YOUR_ACCESS_TOKEN>

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

احمِ فرع `main`

حماية main تحول «المراجعة قبل الدمج» من توصية إلى قاعدة مفروضة. عند حماية الفرع، لن يستطيع الوكيل تنفيذ دمج مباشر، وسيضطر إلى استخدام:

apidog merge-request create

راجع كل تغيير قبل الدمج

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

حذف لمسارات أو مخططات
تغييرات في الحقول المطلوبة
تعديلات على أنواع البيانات
تغييرات في سيناريوهات الاختبار

فوّض التنفيذ واحتفظ بالحكم

النمط الآمن هو:

فوّض مهمة محددة للوكيل.
دعه يعمل داخل فرع معزول.
راجع النتيجة.
اقبل أو ارفض الدمج.

ينطبق ذلك على الاختبارات أيضًا: يمكن للوكيل تشغيلها، لكن عليك التحقق من نتائج أداة الاختبار (test harness) ورمز الخروج قبل الوثوق بالنتيجة.

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

سير العمل الكامل

يمكنك تسليم هذه الخطوات إلى وكيل أو تشغيلها بنفسك:

أنشئ فرع AI من main باستخدام apidog branch create --type ai.
استورد الموارد المطلوبة فقط باستخدام apidog branch pick-to.
دع الوكيل ينفذ التعديلات داخل الفرع.
راجع الفروقات عبر CLI أو عميل Apidog.
أنشئ طلب دمج إلى main المحمي باستخدام apidog merge-request create.
وافق على التغييرات أو ارفضها بعد المراجعة.
أرشف الفرع باستخدام apidog branch archive بعد الدمج أو التخلي عن المهمة.

في هذا التدفق، لا يملك الوكيل مسارًا مباشرًا للكتابة فوق نقطة نهاية أو حذفها على main. أسوأ ما يمكن أن يفعله هو تعديل نسخة مؤقتة ترفض دمجها.

امنح الوكلاء مساحة للعمل دون تسليمهم المفاتيح

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

ضع كتاباتهم في مكان آمن بدلًا من إبطائهم:

فرع AI معزول
فرع main محمي
رموز وصول بأقل امتيازات
مراجعة إلزامية قبل الدمج

بهذا تتحول عبارة «الوكيل دمر واجهة برمجة التطبيقات» إلى فروقات تراجعها وترفضها قبل أن تصل إلى الإنتاج.

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

أفضل أدوات CLI خفيفة الوزن لتصميم API

Yusuf Khalidd — Tue, 14 Jul 2026 03:08:40 +0000

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

جرّب Apidog اليوم

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

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

ما الذي يجعل أداة CLI خفيفة الوزن؟

الأداة خفيفة الوزن هنا لا تعني أنها تملك ميزات أقل، بل أنها تؤدي مهمة محددة بسرعة وباعتماديات قليلة. ابحث عن هذه الخصائص:

تثبيت صغير أو تشغيل مباشر: ملف ثنائي واحد أو أمر npx أفضل من أداة تحتاج إلى خدمة دائمة أو إعداد طويل.
نتيجة مفيدة بدون إعداد أولي: يجب أن تعمل الأداة بمجرد تمرير ملف OpenAPI إليها.
قابلة للبرمجة: مخرجات قابلة للفلترة، ورموز خروج واضحة، وتشغيل مناسب محلياً وفي CI.

ابدأ بالأداة التي تحل المشكلة الحالية، ثم أضف الأدوات الأخرى عند الحاجة.

Redocly CLI: تدقيق وتجميع مواصفات OpenAPI

Redocly CLI مناسبة عندما تريد تدقيق مواصفة أو دمج مواصفة موزعة على عدة ملفات بدون تثبيت عالمي. استخدمها مباشرة عبر npx:

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

استخدم lint للحصول على فحص سريع للمواصفة، واستخدم bundle عندما تعتمد المواصفة على ملفات متعددة عبر $ref.

مثال لبنية متعددة الملفات:

openapi/
├── openapi.yaml
├── paths/
│   └── users.yaml
└── schemas/
    └── user.yaml

بعد التجميع، تحصل على ملف واحد يمكن تمريره إلى مولدات الكود أو أدوات التوثيق:

npx @redocly/cli@latest bundle openapi/openapi.yaml -o dist/openapi.yaml

تقسيم المواصفات حسب الموارد يحافظ على سهولة مراجعة التغييرات ويقلل تعارضات الدمج، خصوصاً في سير عمل تصميم واجهات برمجة التطبيقات الأصلي لـ Git.

الأفضل لـ: تجميع المواصفات متعددة الملفات مع تدقيق سريع.

الحد: قواعد التدقيق الافتراضية أخف من قواعد فريق مخصصة؛ استخدم Spectral عند الحاجة إلى فرض أسلوب تفصيلي.

Spectral: فرض قواعد أسلوب API ككود

Spectral هو مدقق مفتوح المصدر من Stoplight، مرخص بموجب Apache-2.0. يدعم OpenAPI 3.x وOpenAPI 2.0 وAsyncAPI وArazzo، ويمكنه تشغيل قواعد مدمجة أو قواعد خاصة بفريقك.

ثبته وشغل التدقيق الأساسي:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

بدون ملف إعداد، يطبق Spectral مجموعة قواعد oas المدمجة ويشير إلى المشاكل الشائعة، مثل الأوصاف المفقودة أو الأمثلة غير الصالحة أو الأخطاء الهيكلية.

لتحويل دليل أسلوب الفريق إلى قواعد قابلة للتنفيذ، أضف ملف .spectral.yaml:

extends:
  - spectral:oas

rules:
  operation-id-required:
    description: كل عملية يجب أن تحتوي على operationId
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

ثم شغل:

spectral lint openapi.yaml

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

الأفضل لـ: فرض دليل نمط API ككود.

الحد: يفحص Spectral مواصفة واحدة ولا يقارن الإصدارات؛ استخدمه مع أداة مقارنة مثل oasdiff.

oasdiff: كشف التغييرات الجذرية بين الإصدارات

المدقق يحدد إن كانت المواصفة سليمة، لكنه لا يخبرك إن كان حذف حقل أو تغيير نوعه سيكسر العملاء الحاليين. oasdiff يعالج هذه المشكلة. هو ملف ثنائي مكتوب بـ Go ومرخص بموجب Apache-2.0.

ثبته باستخدام Go:

go install github.com/oasdiff/oasdiff@latest

ثم قارن إصدارين:

oasdiff breaking old-openapi.yaml new-openapi.yaml

الأوامر الأساسية:

# اعرض التغييرات التي قد تكسر العملاء فقط
oasdiff breaking old-openapi.yaml new-openapi.yaml

# اعرض سجل تغييرات قابل للقراءة
oasdiff changelog old-openapi.yaml new-openapi.yaml

# اعرض الفرق الكامل القابل للمعالجة آلياً
oasdiff diff old-openapi.yaml new-openapi.yaml

أضفه إلى CI لمنع دمج تغييرات جذرية غير مقصودة:

oasdiff breaking main-openapi.yaml openapi.yaml

إذا أرجع الأمر رمز خروج غير صفري، يمكن لخط أنابيب CI إيقاف البناء قبل الدمج.

الأفضل لـ: منع التغييرات الجذرية في CI بإعداد محدود.

الحد: يقارن المواصفات فقط؛ يجب أن تبقي مواصفة OpenAPI متوافقة مع سلوك API الحقيقي.

Optic: التدقيق والمقارنة في أداة واحدة

Optic أداة مرخصة بموجب MIT تجمع بين تدقيق OpenAPI ومقارنة الإصدارات. تثبيتها واستخدامها الأساسيان مباشران:

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

لكن هناك تحذير مهم: تم أرشفة مستودع Optic العام في يناير 2026 ولم يعد المشروع قيد الصيانة. ما زال المصدر المرخص بموجب MIT متاحاً، وقد تجده في مسارات عمل قائمة، لكنه لن يحصل على قواعد جديدة أو إصلاحات أمنية.

للمشاريع الجديدة، استخدم oasdiff لاكتشاف التغييرات الجذرية وSpectral أو Redocly للتدقيق.

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

الحد: مشروع قديم غير مُصان؛ خطط للانتقال منه.

openapi-generator: توليد SDKs وserver stubs والوثائق

openapi-generator يولد عملاء SDK، ومسودات خوادم، ووثائق من مواصفات OpenAPI. هو الأثقل في هذه القائمة لأنه يعمل على JVM، لكنه يبقى مناسباً للاستخدام اليومي عبر CLI.

ثبته:

npm install -g @openapitools/openapi-generator-cli

أنشئ عميلاً TypeScript باستخدام Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

غيّر قيمة -g بحسب اللغة المستهدفة:

# عميل Go
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# عميل Python
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# مسودة خادم Java
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server

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

الأفضل لـ: إبقاء SDKs والوثائق والكود المُولد متزامناً مع OpenAPI.

الحد: يتطلب JDK 11 أو أحدث، وجودة الكود المُولد تختلف حسب المولد واللغة.

Apidog CLI: تصميم نقاط النهاية والمخططات من الطرفية

الأدوات السابقة تفحص أو تحول مواصفة موجودة. Apidog يغطي خطوة التصميم قبل ذلك: إنشاء نقاط النهاية ومخططات البيانات ثم تصديرها كـ OpenAPI.

ثبت apidog-cli:

npm install -g apidog-cli

سجل الدخول باستخدام رمز وصول، ثم استعرض موارد التصميم وصدّر المواصفة:

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog schema list
apidog export --format openapi -o openapi.yaml

يوفر CLI مجموعات أوامر لـ:

endpoint
schema
security-scheme
folder
mock
import
export

بعد تصدير OpenAPI، مرر الملف إلى بقية السلسلة:

# تدقيق قواعد الأسلوب
spectral lint openapi.yaml

# مقارنة تغييرات الإصدار
oasdiff breaking old-openapi.yaml openapi.yaml

# توليد عميل
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

مخرجات CLI هي JSON منظم وتتضمن agentHints.nextSteps، ما يسهل ربط الأوامر بخطوات آلية أخرى. راجع دليل Apidog CLI الكامل للاطلاع على جميع الأوامر.

الأفضل لـ: تصميم نقاط النهاية والمخططات ثم تصدير OpenAPI من مكان واحد.

الحد: ليس مدقق OpenAPI وليس مفتوح المصدر؛ استخدمه مع Spectral وRedocly وoasdiff بدلاً من اعتباره بديلاً عنها.

كيف تختار الأداة المناسبة؟

معظم الفرق لا تستخدم أداة واحدة فقط. استخدم الأداة المطابقة للمهمة:

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟	ملاحظات
Redocly CLI	التجميع + تدقيق سريع	`npx @redocly/cli@latest`	نعم، MIT	مناسب للمواصفات متعددة الملفات
Spectral	تدقيق دليل الأنماط	`npm i -g @stoplight/spectral-cli`	نعم، Apache-2.0	يدعم قواعد مخصصة
oasdiff	كشف التغييرات الجذرية	`go install github.com/oasdiff/oasdiff@latest`	نعم، Apache-2.0	ملف Go ثنائي واحد وقيد الصيانة
Optic	التدقيق والمقارنة معاً	`npm i -g @useoptic/optic`	نعم، MIT	مؤرشف منذ يناير 2026
openapi-generator	SDKs وstubs ووثائق	`npm i -g @openapitools/openapi-generator-cli`	نعم، Apache-2.0	يتطلب JDK 11+
Apidog CLI	تصميم نقاط النهاية وتصدير المواصفات	`npm i -g apidog-cli`	لا، طبقة مجانية	يصمم ويصدر OpenAPI، وليس مدققاً

سير عمل عملي في CI

يمكن أن يبدو خط الأنابيب البسيط بهذا الشكل:

# 1. صدّر أو اجمع المواصفة
npx @redocly/cli@latest bundle openapi/openapi.yaml -o dist/openapi.yaml

# 2. افحص قواعد الأسلوب
spectral lint dist/openapi.yaml

# 3. امنع التغييرات الجذرية
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 4. ولّد العميل عند الحاجة
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client

ابدأ بتصميم النقاط والمخططات في Apidog CLI، ثم صدّر OpenAPI. استخدم Spectral لفرض قواعد الفريق، وRedocly لتجميع المصادر متعددة الملفات، وoasdiff لحماية المستهلكين من التغييرات الجذرية. أضف openapi-generator عندما تحتاج إلى SDKs أو مسودات خوادم.

لخيارات أوسع خارج أدوات CLI، راجع بدائل Swagger لتصميم واجهات برمجة التطبيقات واختبارها ودليل كيفية تصميم واجهات برمجة تطبيقات REST.

الخلاصة

يمكن أن تكون سلسلة أدوات تصميم API بسيطة وقابلة للتنفيذ بالكامل من الطرفية:

استخدم Redocly CLI للتجميع والتدقيق السريع.
استخدم Spectral لفرض قواعد الأسلوب.
استخدم oasdiff لمنع التغييرات الجذرية.
استخدم openapi-generator لتوليد العملاء والوثائق.
تعامل مع Optic كخيار قديم في المشاريع الموجودة.
استخدم Apidog CLI لتصميم نقاط النهاية والمخططات ثم تصدير OpenAPI.

إذا كنت تفضل تصميم نقاط النهاية والمخططات في مكان واحد قبل تمرير المواصفة إلى أدوات التدقيق والتوليد، نزّل Apidog وجرب apidog-cli.

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

Yusuf Khalidd — Tue, 14 Jul 2026 02:38:04 +0000

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

جرّب Apidog اليوم

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

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

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

تقرأ الأدوات التالية مواصفات 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

متى تستخدمه؟

استخدم 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: تم العثور على تغييرات كاسرة

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

oasdiff changelog main-spec.yaml pr-spec.yaml

مثال في CI

oasdiff breaking openapi/main.yaml openapi/openapi.yaml

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

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

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

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

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

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

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

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

تدفق مقترح

أنشئ فرعًا لتعديل المواصفات.
عدّل openapi.yaml.
شغّل optic diff مقابل main.
أضف الأمر إلى 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

يمكنك إدراج ناتج 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

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

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

تدفق عملي

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"

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

الحد: 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

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

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

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

الحد: لا يفهم دلالات 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

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

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

sprint لميزة أو إصدار محدد.
general للعمل المستمر.
ai لفرع معزول يعدّل فيه وكيل الموارد دون لمس المصدر الأساسي.

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

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

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

apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2

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

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

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

apidog git-connection --help

تنتج الأوامر 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."

مكدس للنشر بعد نجاح 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

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

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

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

apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2

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

خاتمة

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

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

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

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

كيفية إنشاء وثائق API بواسطة وكيل AI مع Apidog CLI

Yusuf Khalidd — Mon, 13 Jul 2026 06:59:48 +0000

توثيق واجهات برمجة التطبيقات (API documentation) مهمة يتفق الجميع على أهميتها، لكن غالبًا ما تتأخر: تُطلق نقطة نهاية جديدة، ويتأخر التوثيق المرجعي، أو يصف دليل البدء السريع تدفق مصادقة لم يعد مستخدمًا. العمل ضروري، لكنه متكرر وسهل التأجيل.

جرّب Apidog اليوم

هذا النوع من العمل — مهم، متكرر، وقابل للتأجيل — مناسب لوكلاء الذكاء الاصطناعي. إذا كان الوكيل يستطيع تشغيل أوامر الطرفية، فيمكنه إنشاء نقاط النهاية، وكتابة الأدلة، ونشر موقع التوثيق من طلب بلغة طبيعية. تجعل Apidog CLI ذلك ممكنًا لأن كل عملية توثيق هي أمر قابل للبرمجة يعيد مخرجات JSON منظمة يمكن للوكيل قراءتها والتصرف بناءً عليها.

لماذا تستخدم CLI بدلًا من GUI أو خادم MCP؟

هناك ثلاث طرق لتفاعل الوكيل مع توثيق API، ولكل منها استخدام مختلف:

النهج	الاتجاه	من يقوده	فرق قابل للمراجعة؟
الواجهة الرسومية (GUI)	تعديلات بشرية في المتصفح	شخص عبر النقرات	لا
خادم MCP	يقرأ المواصفات ← يكتب الكود	وكيل داخل محرر الكود	في مستودع الكود، وليس في التوثيق
واجهة سطر الأوامر (CLI)	يكتب التوثيق نفسه	وكيل في الطرفية	نعم، كل أمر مسجل

يعد خادم MCP مناسبًا عندما تريد من الوكيل أن يقرأ تعريف API ويولد كود العميل بناءً عليه. ويُعد تدفق توثيق Cursor عبر MCP مثالًا على ذلك.

هنا نحتاج إلى العكس: أن ينتج الوكيل التوثيق عبر إنشاء نقاط النهاية، وكتابة أدلة Markdown، ونشر موقع.

تتفوق CLI لثلاثة أسباب:

حتمية: الأمر نفسه يعطي النتيجة نفسها.
قابلة للبرمجة: يمكن تشغيل التدفق بالكامل ضمن CI.
تعيد JSON: تتضمن كل استجابة الحقل agentHints.nextSteps لمساعدة الوكيل على اختيار الخطوة التالية.

بدل أن يخمن الوكيل ما يجب فعله، يتبع اقتراحات CLI مباشرة.

إعداد بيئة الوكيل

ثبّت Apidog CLI وسجّل الدخول مرة واحدة. راجع دليل التثبيت لإعداد Node والمسار، ودليل المصادقة لاستخدام الرموز والأسرار في CI.

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

احصل على الرمز المميز من تطبيق Apidog عبر:

صورة المستخدم → إعدادات الحساب → رمز الوصول إلى API

يُخزن الرمز محليًا بعد تسجيل الدخول، لذلك لا يحتاج الوكيل إلى تمريره مع كل استدعاء.

تُنفذ عمليات الكتابة باستخدام معرف المشروع (Project ID). يمكنك العثور عليه في:

إعدادات المشروع → الإعدادات الأساسية

أو عبر الأمر التالي:

apidog project list

يمكن لأي وكيل برمجة قادر على تشغيل أوامر shell استخدام هذا التدفق، مثل Claude Code وCursor وCodex.

طقوس الكتابة التي يجب أن يتبعها الوكيل

أوامر التوثيق التي تنشئ موارد تتطلب ملف JSON. لا ينبغي للوكيل إنشاء JSON يدويًا من الذاكرة؛ أسماء الحقول المتخيلة هي سبب شائع للفشل.

استخدم دائمًا هذه الخطوات الأربع:

# 1. اطلب من CLI مخطط الحمولة
apidog cli-schema get doc-create

# 2. أنشئ ملف JSON بالاعتماد على المخطط

# 3. تحقق محليًا قبل الكتابة
apidog cli-schema validate doc-create --file ./doc.json

# 4. شغّل أمر الإنشاء
apidog doc create --project <projectId> --file ./doc.json

أضف القواعد التالية إلى مطالبة النظام للوكيل أو إلى ملف CLAUDE.md أو .cursorrules:

قواعد Apidog CLI:
- لا تنشئ حمولة JSON يدويًا. شغّل `apidog cli-schema get` أولًا وابنِ الحمولة من المخطط.
- تحقّق من كل ملف عبر `apidog cli-schema validate ... --file ...` قبل أي عملية إنشاء أو تحديث.
- مرّر `--project ...` دائمًا مع أوامر الكتابة.
- اقرأ `agentHints.nextSteps` في كل استجابة JSON لاختيار الأمر التالي.
- إذا حُظرت عملية كتابة بسبب الأذونات، فتوقف واطلب تدخلًا بشريًا؛ لا تبحث عن حل بديل.

هذه الحلقة:

cli-schema get → cli-schema validate → create

تحول الخطأ من «الوكيل اخترع حقلًا» إلى «المدقق رفض الملف محليًا قبل التنفيذ».

الخطوة 1: إنشاء المرجع من نقاط النهاية والمخططات

في Apidog، يُبنى مرجع API من نقاط النهاية ومخططات البيانات داخل المشروع. ابدأ بإنشاء المخططات القابلة لإعادة الاستخدام، ثم أنشئ نقاط النهاية التي تشير إليها.

لنفترض أن الطلب هو:

أضف نقطة النهاية POST /refunds التي تستقبل معرف طلب ومبلغًا، ووثق استجابات النجاح وخطأ التحقق.

ابدأ بمخطط بيانات للاسترداد. بعد تشغيل:

apidog cli-schema get schema-create

أنشئ ملف refund-schema.json:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}

تحقق من الملف وأنشئ المخطط:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

بعد ذلك، أنشئ نقطة النهاية. يعرض مخطط endpoint-create الحقول المطلوبة مثل method وpath. يمكنك الإشارة إلى المخطط الذي أنشأته باستخدام $ref بالتنسيق التالي:

#/definitions/{schemaId}

أنشئ ملف refunds-endpoint.json:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

ثم نفّذ:

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

يصبح مرجع نقطة النهاية /refunds موجودًا فورًا في المشروع. لا تحتاج إلى خطوة منفصلة لتصدير المرجع؛ لأنه يُعرض من تعريف API نفسه، ما يمنع انحراف التوثيق عن المخطط الفعلي.

الخطوة 2: كتابة الأدلة، وليس المرجع فقط

المرجع المُنشأ من المخططات ليس كافيًا وحده. تحتاج أيضًا إلى أدلة عملية مثل:

صفحة بدء سريع
شرح المصادقة
ملاحظات الترحيل
أدلة حالات الاستخدام

في Apidog، تُخزن هذه الأدلة كمستندات Markdown ضمن شجرة وثائق المشروع، وتديرها أوامر doc.

يعرض مخطط doc-create أن name مطلوب، بينما يحتوي content على Markdown، ويحدد folderId موقع المستند في الشجرة. القيمة 0 تمثل الجذر.

أنشئ ملف quickstart.json:

{
  "name": "البدء السريع: أول عملية استرداد لك",
  "content": "# البدء السريع\n\nيأخذك هذا الدليل من مفتاح API إلى أول عملية استرداد لك في خمس دقائق...",
  "folderId": 0
}

ثم نفّذ:

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

يمكنك الآن إعطاء الوكيل طلبًا مباشرًا مثل:

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

سيكتب الوكيل Markdown، ويضعه في الحمولة الصحيحة، ويتحقق منه، ثم ينشئ المستند دون الحاجة إلى متصفح أو نسخ ولصق.

الخطوة 3: نشر موقع التوثيق

بعد إنشاء المرجع والأدلة، انشر موقع التوثيق من الطرفية.

من المهم التمييز بين هذه الأوامر:

doc: مستند Markdown داخل شجرة وثائق API للمشروع.
docs-site: موقع توثيق عام مستضاف.
shared-doc: رابط مشاركة لإرساله إلى شريك أو عميل، وليس موقعًا كاملًا.

ابدأ باستعراض المواقع الحالية، ثم احصل على المخطط وأنشئ الموقع:

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

استخدم docs-site عند الحاجة إلى موقع عام مستضاف، واستخدم shared-doc إذا كنت تحتاج فقط إلى رابط مشاركة.

الخطوة 4: تصدير نسخة محمولة

قد تحتاج أحيانًا إلى التوثيق كملف:

HTML للاستضافة في مكان آخر
Markdown لمولد موقع ثابت
OpenAPI لمشاركته مع جهات أخرى

استخدم export:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

إذا كان مشروعك يتضمن عدة خدمات، راجع الخيارات المتاحة عبر:

apidog export --help

استخدم الخيارات التالية لتضييق نطاق التصدير:

--scope
--api-ids
--folder-ids

مثال كامل من البداية إلى النهاية

لنفترض أنك تطلب من الوكيل ما يلي:

لقد أضفنا للتو خدمة مدفوعات تتضمن POST /refunds وGET /refunds/{id}. وثّق كليهما، واكتب دليلًا قصيرًا يشرح مفاتيح عدم التكرار (idempotency keys)، وانشره على موقع توثيقاتنا.

يمكن للوكيل تنفيذ التسلسل التالي:

# إنشاء نموذج البيانات المشترك
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# إنشاء نقطتي النهاية
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# إنشاء دليل عدم التكرار كوثيقة Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# نشر الموقع
apidog docs-site create --project $PID --file ./docs-site.json

بعد ذلك، راجع التغييرات الناتجة. بدلًا من قضاء وقت طويل في التنقل بين أدوات متعددة، يصبح العمل طلبًا واضحًا ثم مراجعة.

ربط التدفق بحلقة وكيل أو CI

بما أن كل خطوة هي أمر CLI، يمكنك تشغيل التدفق ضمن CI أو داخل حلقة مهام الوكيل.

هذا مثال بسيط لإعادة إنشاء مرجع Markdown والالتزام به عند كل دفعة:

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

لمزيد من التفاصيل حول تشغيل وكيل باستخدام CLI، راجع:

النمط واحد: صف النية، ودع الوكيل يحولها إلى استدعاءات CLI تم التحقق منها، ثم راجع الناتج.

ملاحظة حول الأذونات

يمكن تقييد عمليات الكتابة التي ينفذها وكيل على المشروع. إذا عادت عملية create محظورة، فهذا يعني أن المشروع عطّل أذونات تحرير AI الخارجية لذلك الفرع.

لديك خياران:

تفعيل إذن التحرير المباشر من: إعدادات المشروع ← إعدادات الميزات ← إعدادات ميزات AI في عميل Apidog 2.8.32+.
تشغيل الوكيل على فرع AI معزول، ثم فتح طلب دمج.

يوضح دليل تحديث مواصفات API باستخدام وكيل تدفق فرع AI بالكامل، وينطبق ذلك أيضًا عند إنشاء التوثيق على فرع محمي.

عقبات شائعة

الوكيل أنشأ JSON يدويًا

هذا هو الفشل الأكثر شيوعًا. افرض التسلسل التالي في تعليمات الوكيل:

cli-schema get → cli-schema validate → create

بهذا يعمل الوكيل من المخطط الفعلي، لا من مخطط متوقع.

معرف المشروع مفقود

تحتاج كل أوامر doc وdocs-site وexport إلى:

--project <projectId>

استخدم معرف المشروع، وليس الاسم المقروء للمشروع.

الخلط بين `doc` و`docs-site` و`shared-doc`

هذه موارد مختلفة:

doc: صفحة Markdown داخل الشجرة
docs-site: موقع مستضاف
shared-doc: رابط مشاركة

اجعل الوكيل يحدد المورد المطلوب قبل تنفيذ أي عملية كتابة.

الرمز المميز غير مضبوط في CI

يخزن apidog login الرمز على الجهاز الحالي. لا يملك مشغل CI جديد هذا الرمز، لذا سجّل الدخول ضمن المهمة نفسها قبل تنفيذ أي أوامر:

apidog login --with-token $APIDOG_TOKEN

واحفظ الرمز في أسرار CI.

مرجع `$ref` يشير إلى مخطط غير موجود

إذا كانت نقطة النهاية تشير إلى مخطط باستخدام:

#/definitions/{schemaId}

فيجب إنشاء المخطط أولًا. أنشئ المخططات قبل نقاط النهاية التي تستخدمها.

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

ما وكلاء الذكاء الاصطناعي التي يمكنها تشغيل Apidog CLI؟

أي وكيل يستطيع تشغيل أوامر shell، مثل Claude Code وCursor وCodex ووكلاء البرمجة المشابهين. CLI مستقلة عن الوكيل؛ المهم هو إرسال أوامر صحيحة وحمولات صالحة.

هل أحتاج إلى خطة مدفوعة؟

لا. Apidog ليس مفتوح المصدر، لكن الطبقة المجانية مع apidog-cli تغطي تدفق الإنشاء والنشر الموضح هنا.

هل يمكن للوكيل حذف وثائق موجودة بالخطأ؟

أمر create يضيف موارد جديدة. تعديل الموارد الموجودة يستخدم update، وله حواجز حماية مختلفة. راجع دليل تحديث مواصفات API للتفاصيل.

كيف يختلف ذلك عن مولدات توثيق AI؟

مولدات التوثيق العامة تنشئ نصًا من الكود. هنا ينشئ الوكيل توثيقًا منظمًا داخل منصة API نفسها: نقاط نهاية، مخططات، أدلة، وموقع منشور، وكلها مرتبطة بمصدر واحد لا ينحرف عما يحرره فريقك.

خاتمة

يمكن لوكيل قادر على تشغيل Apidog CLI أن يتولى مهام التوثيق التي تتأخر عادة: إنشاء نقاط النهاية، وكتابة الأدلة، ونشر الموقع. يتم كل ذلك من طلب بلغة طبيعية، بينما تحمي عملية التحقق من المخطط كل عملية كتابة.

يتحول دورك من كتابة التوثيق يدويًا إلى مراجعة التغييرات.

القاعدة الأساسية هي:

احصل على المخطط → تحقق من الحمولة → أنشئ المورد

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

نزّل Apidog للحصول على CLI، أو راجع دليل Apidog CLI الكامل للاطلاع على مرجع الأوامر.

أفضل أدوات CLI خفيفة الوزن لمحاكاة API

Yusuf Khalidd — Mon, 13 Jul 2026 06:27:11 +0000

تحتاج إلى واجهة برمجة تطبيقات وهمية الآن: ليس خدمة مستضافة، ولا Docker Compose، ولا واجهة رسومية. فقط أمر يقرأ ملفًا ويبدأ بإرجاع الاستجابات على localhost. هذا هو دور خادم المحاكاة الخفيف: وجّهه إلى مواصفات OpenAPI أو ملف بيانات صغير، شغّل أمرًا واحدًا، ثم اربط به الواجهة الأمامية أو اختباراتك إلى أن يصبح الخادم الخلفي الحقيقي جاهزًا.

جرّب Apidog اليوم

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

ما الذي يجعل أداة محاكاة CLI خفيفة الوزن؟

لا تعني الخفة عدد ميزات أقل فقط؛ بل تعني الوصول إلى أول استجابة بأقل بصمة وأقل إعداد. قيّم الأداة وفق هذه النقاط:

حجم التثبيت وبيئة التشغيل: أداة Node تعمل عبر npx تحتاج عادةً إلى Node.js فقط. أما خادم JVM مستقل فيحتاج إلى Java وملف JAR أكبر.
زمن البدء: يجب أن يعمل الخادم قبل أن تغادر المحرر. غالبًا تبدأ أدوات Node خلال أقل من ثانية.
الانتقال من ملف إلى استجابة: الأفضل أن تحتاج إلى ملف واحد وأمر واحد فقط.
العمل من الطرفية أولًا: لا حسابات ولا لوحات تحكم. يجب أن تعمل الأداة داخل سكربت Shell أو مهمة CI بسهولة.

الأدوات الأولى هنا—Prism وMockoon CLI وjson-server—تعمل مباشرة باستخدام npx من دون تثبيت عالمي.

Prism (Stoplight)

استخدم Prism عندما تملك مواصفات OpenAPI وتريد خادمًا وهميًا يلتزم بها. يقرأ paths وexamples والمخططات من ملف OpenAPI ويحوّلها إلى نقاط نهاية قابلة للاستهلاك.

التشغيل السريع

npx @stoplight/prism-cli mock ./openapi.yaml

سيبدأ Prism افتراضيًا على:

http://127.0.0.1:4010

ما الذي تحصل عليه؟

نقطة نهاية لكل عملية معرفة في المواصفات.
استجابة example عندما تكون قد عرّفت مثالًا.
بيانات مولّدة ومتوافقة مع المخطط عندما لا يوجد مثال.
تحقق من الطلبات الواردة مقابل المواصفات؛ الطلب غير المطابق يمكن أن يرجع 422.

للتثبيت العام:

npm install -g @stoplight/prism-cli
prism mock ./openapi.yaml

الأفضل لـ: فرق التصميم أولًا (spec-first) التي تريد إبقاء المحاكاة متوافقة مع عقد API. Prism مرخص تحت Apache-2.0 ويدعم OpenAPI 3.1 و3.0 و2.0 ومجموعات Postman.

حدود مهمة: Prism عديم الحالة. إذا أرسلت POST لإنشاء مورد، فلن يحتفظ به تلقائيًا لطلب GET لاحق. لذلك حسّن الأمثلة والمخططات في مواصفاتك للحصول على استجابات مفيدة. يناسب هذا النهج سير عمل أدوات محاكاة REST API التي تركز على دقة العقد.

Mockoon CLI

يشغّل Mockoon CLI خادمًا وهميًا من ملف بيئة Mockoon أو ملف OpenAPI بصيغة JSON أو YAML. يمكنك تصميم المسارات بصريًا في تطبيق Mockoon المكتبي، ثم تشغيل البيئة نفسها بدون واجهة رسومية محليًا أو في CI.

التشغيل السريع

npx @mockoon/cli start --data ./mockoon-env.json --port 3000

يمكن أن يشير --data إلى:

ملف بيئة Mockoon مُصدّر.
ملف OpenAPI بصيغة JSON.
ملف OpenAPI بصيغة YAML.

للتثبيت العام:

npm install -g @mockoon/cli
mockoon-cli start --data ./mockoon-env.json --port 3000

إذا كان ملف البيئة من إصدار أقدم، يرحّله CLI في الذاكرة من دون تعديل الملف الأصلي.

الأفضل لـ: فريق يصمم المحاكاة في GUI لكنه يحتاج تشغيلها من الطرفية داخل CI أو على خادم. الأداة مرخصة تحت MIT ولديها صورة Docker رسمية.

حدود مهمة: بناء المسارات المعقدة أسهل في تطبيق سطح المكتب. إذا كنت تريد كتابة كل شيء يدويًا في ملف واحد، فقد يكون Prism أو json-server أبسط.

json-server

استخدم json-server عندما لا تملك مواصفات OpenAPI بعد وتريد خلفية REST عملية فورًا. اكتب بياناتك في JSON، وسيولّد الأداة عمليات CRUD حولها.

أنشئ قاعدة بيانات وهمية

echo '{ "posts": [{ "id": 1, "title": "hello" }] }' > db.json
npx json-server db.json

ثم جرّب نقطة النهاية:

curl http://localhost:3000/posts

أضف سجلًا جديدًا

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{ "title": "منشور جديد" }'

يوفر json-server تلقائيًا:

GET
POST
PUT
PATCH
DELETE

ويكتب بيانات POST وعمليات التعديل مرة أخرى إلى db.json، لذلك تحصل على سلوك حافظ للحالة. كما يدعم التصفية والفرز وتقسيم الصفحات عبر معاملات الاستعلام. تراقب سلسلة 1.x الملف وتعيد التحميل عند تغيّره افتراضيًا.

للتثبيت العام:

npm install -g json-server

الأفضل لـ: مطوري الواجهة الأمامية الذين يحتاجون إلى API REST عاملة خلال دقيقة، قبل وجود الخلفية الفعلية. الأداة مرخصة تحت MIT، وهي من خيارات خوادم المحاكاة خفيفة الوزن لواجهة RESTful API التي لا تتطلب مواصفات.

حدود مهمة: يفترض json-server نمط REST القائم على الموارد. لا يناسب المسارات المخصصة جدًا أو المطابقة الدقيقة للرؤوس والأجسام أو اختبار التزام العقد.

MockServer

اختر MockServer عندما تحتاج إلى تحديد الطلب المتوقع بدقة: الطريقة، والمسار، والرؤوس، ومعاملات الاستعلام، والجسم. يمكنك أيضًا إرجاع تأخيرات أو إخفاقات لاختبار المهلات ومعالجة الأخطاء.

تشغيل الخادم

java -jar mockserver-netty-5.15.0-no-dependencies.jar -p 1080

سيعمل الخادم على المنفذ 1080.

بعد ذلك، أرسل توقعاتك إلى REST API الخاصة بـ MockServer أو أنشئها برمجيًا. لمشاريع Node.js، استخدم الغلاف الرسمي:

npm install mockserver-node

const mockserver = require('mockserver-node');

mockserver.start_mockserver({
  serverPort: 1080
});

الأفضل لـ: اختبارات التكامل التي يجب أن تتحكم بدقة في شكل الطلب والاستجابة، بما في ذلك التأخيرات وحالات الفشل. MockServer مرخص تحت Apache-2.0 ويدعم HTTP وHTTPS والمزيد على منفذ واحد.

حدود مهمة: يحتاج إلى JVM، ولذلك تكون بصمته وزمن بدئه أكبر من أدوات Node. كما أن كتابة التوقعات أكثر تفصيلًا من تمرير ملف OpenAPI. إذا احتجت مقارنة البدائل، راجع بدائل MockServer.

WireMock (مستقل)

WireMock خادم محاكاة راسخ في بيئات Java وJVM. يشغّل ملف JAR المستقل نفس المحرك الذي يمكن تضمينه في اختبارات JUnit، لذلك يمكنك مشاركة التعريفات بين التطوير المحلي والاختبارات.

تشغيل الخادم

java -jar wiremock-standalone.jar --port 8080

سيعمل WireMock على المنفذ 8080.

ضع ملفات التعيين في مجلد mappings/، أو أنشئها عبر JSON API الخاصة به. يستطيع WireMock أيضًا تسجيل حركة مرور API حقيقية وإعادة تشغيلها كتعيينات، وهو مفيد عند محاكاة API خارجية لا تتحكم بها.

تتوفر كذلك صورة Docker رسمية:

wiremock/wiremock

الأفضل لـ: فرق JVM التي تريد استخدام محرك محاكاة واحد في التطوير والاختبارات، وتحتاج إلى التسجيل وإعادة التشغيل. WireMock مرخص تحت Apache-2.0.

حدود مهمة: يحتاج إلى Java ويبدأ ببطء أكبر من بدائل Node. ملفات تعيين JSON قوية، لكنها تتطلب منحنى تعلم أعلى من ملف بيانات بسيط. إذا كنت تعمل في JavaScript، فراجع بدائل Mock Service Worker (MSW) لفهم موقع WireMock مقارنة بالمحاكاة داخل المتصفح.

Apidog CLI

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

Apidog ليس مفتوح المصدر؛ إنه منتج تجاري يوفر طبقة مجانية. يتيح لك ذلك تقليل الحاجة إلى دمج خادم محاكاة مستقل ومشغّل اختبارات وأداة مواصفات يدويًا.

ابدأ من الطرفية

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog mock --help

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

تعمل أوامر mock مع توقعات المحاكاة من السكربتات وCI، إلى جانب أوامر نقاط النهاية والمخططات والبيئات وتشغيل الاختبارات. يكون الناتج JSON منظمًا ويتضمن الحقل agentHints.nextSteps، لذلك يمكن استخدامه بواسطة المطورين ووكلاء الذكاء الاصطناعي. راجع دليل Apidog CLI الكامل لمعرفة سطح الأوامر بالكامل.

الأفضل لـ: الفرق التي تريد حفظ المحاكاة والمواصفات والاختبارات في مكان واحد. نزّل Apidog لتجربة خادم المحاكاة المدمج وCLI على مشروعك.

حدود مهمة: هذه منصة تتطلب مشروعًا وتسجيل دخول، وليست أداة أحادية الغرض مثل json-server. إذا كنت تحتاج محاكاة مؤقتة من ملف واحد، فالأدوات الأخف مناسبة أكثر. أما إذا كنت تصمم API بالفعل في Apidog، فالمحاكاة تكون جزءًا من سير عملك.

كيف تختار

طابق الأداة مع ما تملكه حاليًا:

الأداة	الأفضل لـ	التثبيت	مفتوح المصدر؟	ملاحظات
Prism	خدمة مواصفات OpenAPI كمحاكاة	`npx @stoplight/prism-cli`	نعم، Apache-2.0	دقيق للعقد، عديم الحالة، المنفذ 4010
Mockoon CLI	تشغيل محاكاة صُممت بواجهة رسومية بدون واجهة	`npx @mockoon/cli`	نعم، MIT	يقرأ ملف env أو OpenAPI، وصورة Docker متاحة
json-server	إنشاء REST API فورية من JSON	`npx json-server`	نعم، MIT	CRUD حافظة للحالة، بلا مواصفات، المنفذ 3000
MockServer	مطابقة دقيقة للطلبات	`java -jar mockserver-netty-*.jar`	نعم، Apache-2.0	JVM، غلاف npm متاح، المنفذ 1080
WireMock	تطوير واختبار JVM بمحرك واحد	`java -jar wiremock-standalone.jar`	نعم، Apache-2.0	تسجيل وإعادة تشغيل، Docker، المنفذ 8080
Apidog CLI	محاكاة ومواصفات واختبارات في مشروع واحد	`npm install -g apidog-cli`	لا، طبقة مجانية	محاكاة ذكية تلقائية وتوقعات مدارة

قاعدة سريعة:

لديك OpenAPI؟ استخدم Prism أو Mockoon CLI.
لا تملك سوى بيانات أولية؟ استخدم json-server.
تحتاج مطابقة صارمة للرؤوس أو الأجسام أو التأخيرات؟ استخدم MockServer أو WireMock.
تريد إدارة المحاكاة مع التصميم والاختبارات؟ استخدم Apidog.

إذا لم تكن متأكدًا مما إذا كانت المحاكاة تستحق الإضافة أصلًا، راجع حالات استخدام محاكاة API.

الخلاصة

ابدأ بما لديك:

مواصفات → Prism أو Mockoon CLI.
ملف JSON وبيانات أولية → json-server.
حاجة إلى مطابقة طلبات صارمة → MockServer أو WireMock.
مشروع موحد للتصميم والمحاكاة والاختبارات → Apidog CLI.

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

أفضل أدوات CLI خفيفة الوزن للتطوير

Yusuf Khalidd — Mon, 13 Jul 2026 05:47:51 +0000

يقضي مطور الواجهة الخلفية معظم يومه في حلقة قصيرة: يرسل طلبًا إلى نقطة نهاية، يقرأ استجابة JSON، يعدّل الكود، ثم يكرر. استخدام واجهة رسومية ثقيلة لهذه الدورة يضيف وقت تحميل وخطوات لا تحتاجها في كثير من المهام اليومية.

جرّب Apidog اليوم

أدوات سطر الأوامر (CLI) مناسبة لهذه الحلقة لأنها تبدأ بسرعة، تؤدي مهمة محددة، ويمكن ربطها معًا في سكربتات shell أو مهام CI. ستحتاج غالبًا إلى عميل HTTP، وأداة لمعالجة JSON، وطريقة لكشف خادم محلي، ومراقب ملفات، ومشغل لاختبارات API.

يعرض هذا الدليل عشر أدوات تستحق مكانًا في PATH لمطور الواجهة الخلفية، مع أمر عملي لكل أداة. وللسياق الأشمل حول بناء واجهات برمجة التطبيقات، راجع دليل تطوير API.

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

الخفة لا تعني قلة الميزات فقط؛ بل تعني تقليل الاحتكاك بينك وبين النتيجة. قيّم كل أداة وفقًا لأربعة معايير:

حجم وطريقة التثبيت: ملف ثنائي واحد أو حزمة npx صغيرة أفضل من أداة تسحب بيئة تشغيل وملفات إعداد كثيرة.
سرعة البدء: يجب أن تعمل الأداة فورًا، خصوصًا عندما تستدعيها مرارًا داخل حلقة تطوير.
الإعداد قبل أول نتيجة: الأداة الخفيفة تعطيك نتيجة مفيدة دون مشروع جديد أو حساب أو لوحة تحكم.
قابلية التركيب: تقرأ من stdin، تكتب إلى stdout، وتعيد رمز خروج مناسبًا حتى تعمل داخل pipelines وCI.

الأدوات التالية مرتبة تقريبًا من الأبسط والأكثر تخصيصًا إلى الأدوات التي تدير جزءًا أكبر من سير العمل. أداة curl موجودة غالبًا على جهازك بالفعل.

curl

curl هو الأساس لطلبات HTTP القابلة للبرمجة. استخدمه عندما تحتاج إلى أمر يمكن نسخه إلى سكربت أو مهمة CI دون أي تبعيات إضافية.

curl -s -X POST https://api.github.com/repos/curl/curl/issues \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test issue"}'

استخدم هذه الخيارات حسب المهمة:

-s: إخفاء عداد التقدم لإخراج نظيف.
-i: عرض رؤوس الاستجابة مع الجسم.
-w '%{http_code}': طباعة رمز الحالة.
--fail: إرجاع رمز خروج غير صفري عند استجابات 4xx أو 5xx، وهو مفيد في CI.

curl --fail --silent --show-error \
  -w '\nHTTP %{http_code}\n' \
  https://api.example.com/health

الأفضل لـ: سكربتات shell، فحوصات الصحة، وطلبات CI.

الحدود: بناء جملة الخيارات كثيف، وبناء أو تحليل JSON يدوي نسبيًا.

HTTPie

HTTPie، عبر الأمر http، يجعل الطلبات التفاعلية أسهل للقراءة والكتابة. يرسل JSON افتراضيًا ويعرض استجابات منسقة.

http POST httpbin.org/post name=apidog role=api-tool active:=true

ينتج الأمر جسم JSON مشابهًا للتالي:

{
  "name": "apidog",
  "role": "api-tool",
  "active": true
}

استخدم الصيغ التالية أثناء بناء الطلب:

key=value لقيمة نصية.
key:=value لقيمة JSON خام، مثل الأرقام والقيم المنطقية.
Header:value لإضافة رأس.

http GET https://api.example.com/users \
  Authorization:"Bearer $TOKEN" \
  page:=1

الأفضل لـ: استكشاف API يدويًا عندما تكون قابلية القراءة أهم من الاختصار.

الحدود: يعتمد على Python، لذلك قد يكون بدء تشغيله أبطأ من بديل أصلي مثل xh.

xh

xh يقدم أسلوب HTTPie نفسه تقريبًا، لكنه ملف ثنائي مبني بـ Rust. هذا يجعله مناسبًا للحاويات وصور CI الخفيفة.

xh POST httpbin.org/post name=apidog age:=24

بما أن الصياغة متوافقة مع أسلوب HTTPie، يمكنك استخدام:

xh GET https://api.example.com/users \
  Authorization:"Bearer $TOKEN" \
  limit:=20

يدعم xh أيضًا HTTP/2 وHTTP/3. يمكنك تنزيل الملفات الثنائية الجاهزة من مشروع xh على GitHub.

الأفضل لـ: من يريد سهولة HTTPie مع سرعة بدء أصلية وتثبيت بلا تبعيات.

الحدود: يغطي الاستخدامات الشائعة لـ HTTPie، لكنه لا يهدف إلى تغطية كل الإضافات الممكنة.

jq

jq هو الأداة التي تحول استجابة JSON كبيرة إلى قيمة يمكن أن يستخدمها سكربتك. اربطه مع curl أو xh بدل فحص JSON يدويًا.

curl -s https://api.github.com/repos/stedolan/jq | jq '.stargazers_count'

لاستخراج قيمة نصية خام لاستخدامها في متغير shell، أضف -r:

REPO_NAME=$(curl -s https://api.github.com/repos/stedolan/jq | jq -r '.name')
echo "$REPO_NAME"

أمثلة عملية أخرى:

# استخراج أسماء العناصر من مصفوفة
jq '.items[] | .name'

# تصفية العناصر النشطة
jq '.items[] | select(.active)'

# إنشاء كائن جديد من الاستجابة
jq '{id, name, status}'

الأفضل لـ: استخراج وتحويل حقول JSON في السكربتات وCI.

الحدود: التحويلات المعقدة والمتداخلة تحتاج إلى تعلم صياغة jq.

gh (GitHub CLI)

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

gh pr create --title "Add rate limiting" --body "Closes #42" --base main

أوامر عملية لسير العمل اليومي:

# متابعة فحوصات طلب السحب الحالي
gh pr checks --watch

# متابعة تنفيذ GitHub Actions
gh run watch

# استدعاء GitHub API مباشرة
gh api repos/{owner}/{repo}/issues

سجّل الدخول أولًا:

gh auth login

الأفضل لـ: أتمتة عمليات GitHub، مثل إنشاء PR من CI أو متابعة Actions.

الحدود: مخصص لـ GitHub، ولن يحل محل أدوات GitLab أو Bitbucket.

ngrok

يكشف ngrok منفذًا محليًا عبر رابط عام آمن. استخدمه عند اختبار webhooks أو مشاركة خادم تطوير مع زميل أو خدمة خارجية.

ngrok http 8080

سيعرض ngrok عنوان URL عام من نوع https:// يوجه الطلبات إلى localhost:8080.

لتصحيح webhook، افتح مفتش الطلبات المحلي:

http://127.0.0.1:4040

من هناك يمكنك مراجعة الطلبات التي وصلت وإعادة تشغيلها أثناء التحقيق في مشكلة.

الأفضل لـ: اختبار webhooks، مشاركة بيئة محلية، واختبار استدعاءات الطرف الثالث.

الحدود: خدمة تجارية بطبقة مجانية؛ قد يتغير عنوان URL بين الجلسات وتوجد حدود للاستخدام.

mkcert

mkcert ينشئ شهادات HTTPS موثوقة محليًا. استخدمه عندما تحتاج إلى اختبار سلوك لا يظهر إلا مع HTTPS، مثل ملفات تعريف الارتباط الآمنة أو إعادة توجيه OAuth.

mkcert -install
mkcert localhost 127.0.0.1 myapp.local

نفّذ mkcert -install مرة واحدة لإعداد مرجع مصدق محلي على جهازك. بعد ذلك، أنشئ شهادة للنطاقات المحلية التي يحتاجها خادم التطوير.

مثال عند استخدام اسم محلي مخصص:

mkcert api.localhost app.localhost

ثم مرّر ملفات الشهادة والمفتاح التي أنشأها الأمر إلى خادم التطوير أو الوكيل العكسي.

الأفضل لـ: تشغيل HTTPS محلي موثوق يقترب من سلوك الإنتاج.

الحدود: للتطوير فقط. لا تستخدم شهادات mkcert في الإنتاج، واحمِ مفتاح المرجع المصدق المحلي.

watchexec

watchexec يراقب الملفات ويعيد تشغيل أمر عند حدوث تغيير. يفيد في تقصير دورة التعديل والتشغيل دون الاعتماد على وضع مراقبة خاص بإطار عمل معين.

watchexec -e py -r 'pytest tests/'

في هذا المثال:

-e py يراقب ملفات Python.
-r يوقف العملية السابقة ويعيد تشغيلها بدل تكديس عمليات متعددة.

أمثلة لمشاريع أخرى:

# خادم Go
watchexec -r 'go run .'

# اختبارات JavaScript
watchexec 'npm test'

# تطبيق Node.js
watchexec -e js,json -r 'node server.js'

يحترم watchexec ملف .gitignore افتراضيًا، لذلك لا يعيد التشغيل عادة بسبب مخرجات البناء أو التبعيات المتجاهلة.

الأفضل لـ: إعادة تشغيل خادم محلي أو اختبارات عند الحفظ.

الحدود: يعيد تشغيل العملية فقط؛ لا يقدم إعادة تحميل ساخنة للوحدات أو حفظ حالة العملية.

Docker CLI

Docker CLI أثقل من الأدوات الأخرى لأنه يحتاج إلى Docker daemon وموارد نظام، لكنه عملي جدًا لتشغيل خدمات تطوير قابلة للتخلص منها مثل Postgres وRedis.

docker run --rm -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:16

يعني ذلك:

--rm: حذف الحاوية عند إيقافها.
-e: تعريف متغير بيئة داخل الحاوية.
-p: ربط منفذ الحاوية بمنفذ جهازك.

يمكن لتطبيقك الآن الاتصال بـ:

localhost:5432

مثال Redis سريع:

docker run --rm -p 6379:6379 redis:7

الأفضل لـ: قواعد البيانات والخدمات المساندة لتطوير محلي واختبارات تكامل قابلة للتكرار.

الحدود: ليس خفيفًا من ناحية الموارد، لكنه يوفر طريقة قابلة للبرمجة لتشغيل بنية محلية دون تثبيت الخدمات مباشرة على النظام.

apidog-cli

عند العمل على API من الطرفية، تحتاج أحيانًا إلى الوصول إلى مشروع API نفسه: نقاط النهاية، المخططات، البيئات، وسيناريوهات الاختبار. توفر Apidog أداة apidog-cli لربط هذه الموارد بسير عمل الطرفية.

ثبّت الأداة وسجّل الدخول ثم شغّل سيناريو اختبار محفوظًا:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog run -t <scenario_id> -e <env_id> -r cli

يشغّل apidog run السيناريو مقابل البيئة المحددة ويطبع النتائج في الطرفية. عند نجاح التأكيدات يعيد رمز خروج 0، وعند الفشل يعيد رمزًا غير صفري، لذلك يمكن وضعه مباشرة ضمن بوابة CI.

مثال مبسط في GitHub Actions:

- name: Run API scenario
  run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} -e ${{ secrets.APIDOG_ENV_ID }} -r cli

تغطي CLI أيضًا مجموعات أوامر لإدارة موارد المشروع، منها:

endpoint وschema للتصميم.
import وexport لنقل مواصفات OpenAPI وSwagger وPostman.
mock لإعداد توقعات التقليد.
environment وvariables لإدارة الإعدادات.
run لتشغيل سيناريوهات الاختبار.

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

للتفاصيل، راجع دليل Apidog CLI الكامل ودليل تثبيت Apidog CLI.

الأفضل لـ: تشغيل سيناريوهات اختبار API في CI وإدارة موارد المشروع من السكربتات، خصوصًا في سير عمل تطوير API المعتمد على المواصفات.

ملاحظة: Apidog منتج تجاري بطبقة مجانية وليس مفتوح المصدر. الجزء الخفيف هنا هو apidog-cli، بينما منصة Apidog الكاملة توفر واجهة رسومية فوق المشروع نفسه.

كيف تختار الأداة المناسبة؟

هذه الأدوات مكملة لبعضها غالبًا، وليست بدائل متطابقة. قد تستخدم عميل HTTP مع jq، ثم تضيف ngrok لاختبار webhook، وwatchexec لتشغيل الاختبارات تلقائيًا.

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟
curl	طلبات مبرمجة وفحوصات صحة CI	مثبتة مسبقًا غالبًا	نعم (ترخيص curl)
HTTPie	طلبات تفاعلية قابلة للقراءة	`pip install httpie`	نعم (BSD)
xh	أسلوب HTTPie مع سرعة أصلية	`cargo install xh` أو ملف ثنائي	نعم (MIT)
jq	تصفية استجابات JSON	`brew install jq` أو ملف ثنائي	نعم (MIT)
gh	أتمتة PR وCI على GitHub	`brew install gh` أو ملف ثنائي	نعم (MIT)
ngrok	كشف localhost واختبار webhooks	تحميل ملف ثنائي	لا
mkcert	شهادات HTTPS محلية موثوقة	`brew install mkcert` أو ملف ثنائي	نعم (BSD)
watchexec	إعادة التشغيل عند تغيير الملفات	`cargo install watchexec-cli`	نعم (Apache-2.0)
Docker CLI	خدمات تطوير قابلة للتخلص منها	تثبيت Docker	نعم (Apache-2.0)
apidog-cli	تشغيل السيناريوهات وإدارة المشروع	`npm install -g apidog-cli`	لا

اختصر قرارك حسب المهمة:

إرسال طلبات تفاعلية: xh أو HTTPie.
إرسال طلبات داخل سكربت أو CI: curl.
قراءة وتحويل JSON: jq.
كشف خادم محلي: ngrok.
HTTPS محلي موثوق: mkcert.
إعادة التشغيل عند الحفظ: watchexec.
تشغيل خدمات مثل Postgres وRedis: Docker.
تشغيل اختبارات API وإدارة موارد المشروع: apidog-cli.

خلاصة

المجموعة الجيدة من أدوات CLI ليست كبيرة؛ إنها مجموعة من أدوات سريعة يمكن تركيبها معًا. استخدم curl أو xh لإرسال الطلبات، وjq لتحويل الاستجابات، وngrok وmkcert لمعالجة الوصول المحلي وHTTPS، وwatchexec لتقصير حلقة التعديل والتشغيل، وDocker لتشغيل الخدمات المساندة.

يربط apidog-cli هذه الحلقة بمشروع API الفعلي، بحيث تكون نقاط النهاية والاختبارات التي تشغلها من الطرفية هي نفسها التي يديرها الفريق. نزّل Apidog لإعداد المشروع، ثم استخدم CLI لتشغيل السيناريوهات ضمن مسار CI.

أفضل أدوات CLI خفيفة الوزن لإدارة الـ API

Yusuf Khalidd — Mon, 13 Jul 2026 05:46:42 +0000

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

جرّب Apidog اليوم

في هذا الدليل ستتعرف على أدوات سطر أوامر خفيفة الوزن لإدارة واجهات برمجة التطبيقات دون تثبيت منصة كاملة على جهازك. معظمها ملف Go ثنائي واحد تضيفه إلى PATH، أو حزمة npm تثبتها مرة واحدة، وتندمج مباشرةً مع CI. إذا كنت تقارن منصات إدارة كاملة، فاطلع على أفضل أدوات إدارة واجهات برمجة التطبيقات لعام 2026 ودليل إدارة واجهات برمجة التطبيقات. أما هنا، فالتركيز على أدوات تعمل من الطرفية ويمكن تثبيتها خلال دقيقة.

قبل البدء، ميّز بين نطاقين مختلفين لعبارة «إدارة واجهات برمجة التطبيقات»:

إدارة طبقة البوابة: التوجيه، والمصادقة، وحدود المعدل، والحصص، وكل ما يقف أمام حركة مرور الإنتاج، مثل Kong وTyk وApigee وKrakenD.
إدارة مشروع API: المواصفات، ونقاط النهاية، والبيئات، والمتغيرات، والخوادم الوهمية، والوثائق.

الأدوات التالية تغطي النطاقين. اختر أداة البوابة عندما تدير حركة المرور، واختر أداة المشروع عندما تدير دورة حياة API نفسها.

ستحصل على أوامر تثبيت عملية، وأمر أول مفيد لكل أداة، وملاحظات واضحة عن حدود استخدامها.

ما الذي يجعل أداة CLI خفيفة الوزن؟

لا يعني «خفيفة الوزن» أنها محدودة القدرة. في هذه القائمة، تتأهل الأداة عندما:

تُشحن كملف ثنائي واحد أو حزمة واحدة: مثل ملف Go ثنائي أو حزمة npm عامة. لا تحتاج إلى إعداد مجموعة Kubernetes لتجربتها.
تعمل محليًا وتبدأ بسرعة: شغّلها على ملف مواصفات أو تكوين محلي، واحصل على نتيجة خلال ثوانٍ.
تحتاج إلى إعداد محدود: يجب أن يعمل أول أمر مفيد بعلامة أو اثنتين، لا بملف YAML من 200 سطر.
تتناسب مع CI: توفر رموز خروج واضحة وأوضاع مثل check أو validate أو dry-run وإخراجًا مناسبًا للأتمتة.

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

decK: إدارة Kong Gateway بأسلوب GitOps

decK هي أداة التكوين التعريفي لـ Kong. تصدّر المسارات والخدمات والمكونات الإضافية والمستهلكين من Kong Gateway إلى ملف YAML، ثم تحفظ الملف في Git وتزامنه مع البوابة.

ثبّتها على macOS باستخدام Homebrew:

brew install kong/deck/deck

قبل تطبيق أي تغيير، اعرض الفروقات:

deck gateway diff kong.yaml

ثم طبّق التكوين:

deck gateway sync kong.yaml

يُطابق deck gateway sync حالة Kong مع محتوى kong.yaml، بينما يتيح لك deck gateway diff مراجعة التغييرات قبل تنفيذها.

استخدمها عندما: تدير Kong وتريد GitOps واكتشاف الانجراف بين ملفات Git وحالة البوابة الحية.

الحدود: decK مخصصة لـ Kong فقط، وليست أداة عامة لإدارة جميع أنواع APIs. كذلك، توفر Kong أداة kongctl بسطح أوامر أوسع للمطورين، لذا تحقق من الأداة الأنسب لإصدار Kong الذي تستخدمه.

Tyk CLI: تجميع مكونات Tyk الإضافية

Tyk هي بوابة API مفتوحة المصدر. تركز واجهة CLI الخاصة بها على الأجزاء التي تحتاج إلى أتمتتها حول نشر Tyk، وخصوصًا تجميع حزم المكونات الإضافية.

إذا كنت تكتب برمجيات وسيطة مخصصة باستخدام Go أو Python أو JavaScript، فاجمعها في حزمة يمكن للبوابة تحميلها وقت التشغيل:

tyk bundle build -output bundle.zip

منذ Tyk Gateway v2.8، أصبحت أداة التجميع مدمجة عادةً في الثنائي tyk، لذلك لا تحتاج غالبًا إلى تثبيت tyk-cli منفصلًا.

استخدمها عندما: تحتاج إلى بناء وإدارة مكونات Tyk الإضافية من الطرفية ضمن CI.

الحدود: سطح أوامر Tyk أضيق من decK؛ ما زالت مهام إدارية كثيرة تُنفذ عبر Dashboard API أو Gateway API. كما أنها تفترض أنك تشغّل Tyk بالفعل.

apigeecli: أتمتة Google Apigee

apigeecli هي أداة سطر الأوامر الرسمية لمنصة Google Apigee. بدلاً من إدارة الوكلاء والبيئات ومنتجات API والتطبيقات عبر واجهة Apigee، يمكنك تنفيذها كأوامر قابلة للتكرار داخل pipeline.

ثبّت الأداة باستخدام السكربت الرسمي، ثم اعرض المؤسسات المتاحة:

curl -L https://raw.githubusercontent.com/apigee/apigeecli/main/downloadLatest.sh | sh -
token=$(gcloud auth print-access-token)
apigeecli organizations list -t "$token"

يمكنك بعد ذلك استخدام الأداة لاستيراد حزم API proxy ونشرها وربطها بخطوط CI.

استخدمها عندما: تعمل على Apigee وتحتاج إلى أتمتة النشر وإدارة الموارد دون فتح واجهة المستخدم.

الحدود: الأداة خاصة بـ Apigee، وتحتاج إلى مصادقة Google Cloud مثل رمز الوصول الناتج عن gcloud.

KrakenD: بوابة بلا حالة بتكوين ككود

KrakenD بوابة API بلا حالة مكتوبة بلغة Go. لا تعتمد على قاعدة بيانات أو واجهة إدارة لحفظ الحالة؛ ملف التكوين هو مصدر الحقيقة. لذلك، تعني إدارتها التحقق من ملفات التكوين وقوالبها قبل النشر.

تحقق من صحة التكوين وشغّل linter:

krakend check -c krakend.json --lint

للتكوينات الكبيرة، قسّم الإعدادات إلى قوالب وأجزاء بحسب البيئة:

FC_ENABLE=1 FC_SETTINGS="config/prod" krakend check -c krakend.tmpl

استخدم هذا النمط في CI لمنع نشر تكوينات غير صالحة:

krakend check -c krakend.json --lint && echo "التكوين صالح"

استخدمها عندما: تريد تعريف البوابة بالكامل كملفات قابلة للمراجعة والتحقق في Git وCI.

الحدود: لأنها بلا حالة، لا توجد حالة تشغيلية لإدارتها عبر CLI ولا بوابة مطورين مدمجة. بعض الميزات، مثل SSO وسجل التدقيق، تخص الإصدارات المؤسسية.

Speakeasy: إنشاء وإدارة حزم SDK للعملاء

تتعامل Speakeasy مع جانب المستهلك من API. انطلاقًا من مواصفة OpenAPI واحدة، يمكنك إنشاء SDKs آمنة النوع، وموفري Terraform، واختبارات عقود، ثم إعادة إنشائها عند تغير المواصفة.

ثبّت الأداة وشغّل الإعداد التفاعلي:

brew install speakeasy-api/tap/speakeasy
speakeasy quickstart

بعد الإعداد، استخدم الأمر التالي في CI:

speakeasy run

يتحقق speakeasy run من المواصفة، ويولد حزم SDK، ويجمعها في خطوة واحدة.

استخدمها عندما: تريد شحن SDKs للعملاء وتحديثها تلقائيًا من مواصفة OpenAPI بدلاً من صيانتها يدويًا.

الحدود: تدير أدوات العميل، لا بوابتك ولا حركة مرور الإنتاج. كما أن بعض إمكانات الإخراج متعددة اللغات تتطلب مستويات استخدام مدفوعة.

apidog-cli: إدارة مشروع API والبيئات والمواصفات

بينما تدير الأدوات السابقة البوابات أو SDKs، يدير apidog-cli مشروع API نفسه: التصميم، ونقاط النهاية، والبيئات، والمتغيرات، والاختبارات، والوثائق. وهو مرافق سطر الأوامر لـ Apidog، ويُثبت كحزمة npm عامة.

ثبّت الأداة وسجّل الدخول:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog project list

بعد المصادقة، استخدم مجموعات الأوامر بحسب المورد الذي تديره:

# إدارة البيئات والمتغيرات
apidog environment
apidog variables

# إدارة تصميم API
apidog endpoint
apidog schema

# الاستيراد والتصدير والاختبار
apidog import
apidog export
apidog mock
apidog doc
apidog run

يدعم الاستيراد والتصدير صيغًا مثل OpenAPI وPostman وMarkdown وHTML. كما يوفر إخراج JSON منظمًا يتضمن agentHints.nextSteps، ما يجعله مناسبًا للبرمجة النصية أو لتدفقات عمل وكلاء الذكاء الاصطناعي. راجع دليل إدارة واجهات برمجة التطبيقات دون مغادرة وكلاء الذكاء الاصطناعي.

استخدمها عندما: تريد أداة واحدة لإدارة تصميم API وبيئاته ومتغيراته ومواصفاته ومحاكاته واختباراته ووثائقه من الطرفية أو CI.

الحدود: Apidog ليس بوابة API، لذلك لا يحل محل Kong أو Apigee في طبقة حركة المرور. كما أنه منتج تجاري مع طبقة مجانية، وليس مفتوح المصدر. إذا كنت تبحث عن إعداد headless يعتمد على API أولًا، فراجع أداة إدارة واجهات برمجة التطبيقات غير واجهة المستخدم.

كيف تختار الأداة المناسبة؟

ابدأ بالسؤال الأساسي: هل تدير حركة المرور عند البوابة، أم تدير مشروع API ودورة حياته؟

الأداة	الأفضل لـ	التثبيت	مفتوح المصدر؟	النطاق
decK (Kong)	GitOps واكتشاف الانجراف لـ Kong	`brew install kong/deck/deck`	نعم، Apache 2.0	البوابة، Kong
Tyk CLI	تجميع مكونات Tyk الإضافية	مدمجة في `tyk` منذ 2.8+	نعم، MPL	البوابة، Tyk
apigeecli	أتمتة Google Apigee	`curl .../downloadLatest.sh \	sh -`	نعم، Apache 2.0
KrakenD	بوابة بلا حالة بتكوين ككود	ثنائي أو Docker	نعم، CE Apache 2.0	البوابة
Speakeasy	إنشاء وإصدار SDKs للعملاء	`brew install speakeasy-api/tap/speakeasy`	CLI نعم، Apache 2.0	العميل وSDK
apidog-cli	إدارة المشروع والبيئات والمواصفات	`npm install -g apidog-cli`	لا، مع طبقة مجانية	المشروع ودورة الحياة

اختر وفقًا لما تشغله فعليًا:

تستخدم Kong؟ ابدأ بـ decK.
تستخدم Apigee؟ استخدم apigeecli.
تستخدم Tyk أو KrakenD؟ ابدأ بأدواتهما الأصلية.
تريد تعريف البوابة كملفات فقط؟ KrakenD يناسب هذا النموذج.
تريد إدارة SDKs للعملاء؟ اختر Speakeasy.
تريد إدارة تصميم API والبيئات والمتغيرات؟ استخدم apidog-cli.

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

الخلاصة

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

إذا كان عملك اليومي يركز على التصميم والمحاكاة والاختبار والوثائق في مكان واحد، فإن Apidog يجمع هذه المهام، بينما يدمج apidog-cli هذا العمل في CI وتدفقات عمل الوكلاء. نزّل Apidog لتجربة المنصة، ثم استخدم CLI عندما تحتاج إلى أتمتة العمل. ابدأ بأداة واحدة، أضفها إلى خط الأنابيب، ثم توسع حسب الحاجة.

أفضل أدوات CLI خفيفة لاختبار API

Yusuf Khalidd — Mon, 13 Jul 2026 05:45:32 +0000

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

جرّب Apidog اليوم

تعني «خفيفة الوزن» هنا: تثبيت صغير، وبدء تشغيل سريع، وتكوين محدود للطلب الأول، ومخرجات مناسبة للمحطة الطرفية يمكن تمريرها إلى jq أو grep. لا يتعلق الاختيار بأكثر الأدوات ميزات، بل بأقل احتكاك ممكن. للحصول على مقارنة أوسع تشمل الواجهات الرسومية المستضافة أيضًا، راجع أفضل أدوات اختبار API المجانية.

في هذا الدليل ستجد ثماني أدوات CLI لاختبار REST وHTTP، من الطلبات اليدوية السريعة إلى تشغيل مجموعات اختبار كاملة في CI. يتضمن كل قسم أمر تثبيت، ومثالًا قابلًا للتنفيذ، وحالة الاستخدام المناسبة، والقيود العملية.

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

ليست كل أداة تعمل في المحطة الطرفية خفيفة فعلًا. استخدم هذه المعايير قبل اختيارها:

بصمة صغيرة: ملف تنفيذي واحد، أو تثبيت pip/npm بسيط، أو أمر npx. يفضّل عدم الحاجة إلى daemon أو إعداد runtime مسبقًا.
بدء تشغيل سريع: يجب أن ترسل الأداة الطلب فورًا دون تسخين أو تحميل واجهة.
تكوين اختياري: أرسل أول طلب دون حساب أو مشروع أو ملف إعدادات.
مخرجات مناسبة للمحطة الطرفية: نتائج سهلة القراءة والتوجيه، مع رموز خروج مفيدة لـ CI.

إذا كان هدفك فحص نقطة نهاية يدويًا، فراجع أيضًا بدائل curl لاختبار REST API.

curl: الأساس المثبت بالفعل

غالبًا ما يكون curl مثبتًا مسبقًا على macOS ومعظم توزيعات Linux وإصدارات Windows الحديثة. لذلك، أخف تثبيت هو عدم تثبيت شيء.

# تحقق من الإصدار
curl --version

# أرسل JSON واطبع رمز حالة HTTP فقط
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"user":"acme","plan":"pro"}'

الأفضل لـ: الطلبات لمرة واحدة، والسكريبتات، والبيئات التي لا تسمح بتثبيت أدوات إضافية.

القيود: تضبط الرؤوس يدويًا، ولا ينسّق JSON افتراضيًا، وتحتاج إلى jq أو منطق shell لتأكيد الاستجابة. curl يرسل ويعرض؛ لكنه ليس محرك اختبارات.

HTTPie: curl للبشر

يوفر HTTPie صياغة أبسط للطلبات اليدوية. استخدم key=value للحقول النصية وkey:=value للقيم الرقمية أو JSON، مع مخرجات ملونة ومنسقة افتراضيًا.

python -m pip install httpie
# أو: brew install httpie

# age:=24 يرسل رقمًا، وname=acme يرسل نصًا
http POST httpbin.org/post name=acme age:=24 plan=pro

الأفضل لـ: استكشاف API يدويًا عندما تريد مخرجات مقروءة وأوامر أقل تعقيدًا.

القيود: يعتمد على Python، لذا يكون بدء تشغيله أبطأ من ملف تنفيذي مترجم. ومثل curl، أنت تقرأ الاستجابة بدلًا من تشغيل تأكيدات اختبار عليها.

xh: تجربة HTTPie في ملف تنفيذي واحد

يعيد xh تنفيذ صياغة HTTPie بلغة Rust. تحصل على أوامر مألوفة ومخرجات ملونة، لكن مع بدء أسرع وبدون runtime مثل Python.

brew install xh
# أو: cargo install xh --locked

# صياغة مشابهة لـ HTTPie مع بدء أسرع
xh POST httpbin.org/post name=acme age:=24 plan=pro

يمكنك أيضًا عرض أمر curl المكافئ:

xh --curl GET https://httpbin.org/get

الأفضل لـ: من يفضل تجربة HTTPie لكن يريد ملفًا تنفيذيًا سريعًا وخفيفًا.

القيود: لا يدعم جميع ميزات HTTPie، ولا يملك نظام إضافات مماثلًا. وهو عميل HTTP، لا محرك تأكيدات.

Hurl: اختبارات نصية بسيطة تعمل في CI

ينقل Hurl العمل من «إرسال طلب» إلى «اختبار استجابة». اكتب الطلبات والتأكيدات في ملف .hurl نصي ثم شغّله في جهازك أو في CI.

brew install hurl
# أو: cargo install --locked hurl

cat > login.hurl <<'EOF'
POST https://httpbin.org/post
{ "user": "acme", "plan": "pro" }

HTTP 200
[Asserts]
jsonpath "$.json.user" == "acme"
EOF

# يعيد رمز خروج غير صفري عند فشل أي تأكيد
hurl --test login.hurl

الأفضل لـ: اختبارات العقود وSmoke tests المخزنة في التحكم بالإصدار كنص قابل للمراجعة.

القيود: يركز على HTTP، لذلك لا يشغّل gRPC ولا يولد حملًا فعليًا. التدفقات المعقدة قد تعني المزيد من ملفات .hurl بدلًا من منطق برمجي كامل.

Step CI: ملف YAML واحد لتدفق متعدد الخطوات

يتيح Step CI وصف تدفق API كامل في YAML: تسجيل دخول، التقاط token، استخدامه في طلب تالٍ، ثم التحقق من النتيجة. يدعم REST وGraphQL وgRPC وtRPC وSOAP، ويمكنه التحقق من مواصفات OpenAPI.

npm install -g stepci

# يحتوي workflow.yml على الخطوات والمتغيرات والتأكيدات
stepci run workflow.yml

الأفضل لـ: الفرق التي تحتاج إلى ملف تصريحي واحد لتدفق API متعدد الخطوات يعمل محليًا وفي CI بالطريقة نفسها.

القيود: يعتمد على Node.js، لذا فهو أثقل من أدوات Rust أو Go ذات الملف التنفيذي الواحد. تحقق من نشاط المستودع قبل اعتماده كأساس لمسار عمل طويل الأجل.

للتخطيط لمستويات الاختبار المختلفة، راجع استراتيجيات اختبار API.

k6: اختبار الحمل من المحطة الطرفية

يجيب k6 عن سؤال الأداء: هل ستصمد API تحت الحمل؟ وهو ملف تنفيذي مبني بلغة Go يستخدم JavaScript لكتابة السيناريوهات. يمكن للـ thresholds تحويل اختبار الأداء إلى نتيجة نجاح أو فشل مناسبة لـ CI.

brew install k6
# أو عبر Docker: docker run grafana/k6

cat > load.js <<'EOF'
import http from 'k6/http';
import { check } from 'k6';

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    http_req_duration: ['p(95)<500'],
  },
};

export default function () {
  const res = http.get('https://httpbin.org/get');
  check(res, {
    'status is 200': (r) => r.status === 200,
  });
}
EOF

k6 run load.js

الأفضل لـ: اختبارات الحمل والأداء القابلة للبرمجة والتي تريد تشغيلها في CI دون إعداد cluster.

القيود: ليس عميل اختبار وظيفي يدويًا؛ لن تستخدمه لفحص استجابة واحدة بسرعة. كما يتطلب كتابة سيناريوهات JavaScript مفيدة.

Newman: تشغيل مجموعات Postman بدون واجهة رسومية

Newman هو مشغل سطر الأوامر لمجموعات Postman. صدّر المجموعة، وصدّر البيئة عند الحاجة، ثم شغّل الاختبارات نفسها في CI.

npm install -g newman

# collection.json مُصدّر من Postman
# -e يمرر ملف البيئة
newman run collection.json -e staging.json

الأفضل لـ: الفرق التي تستخدم Postman بالفعل وتريد تشغيل مجموعاتها الحالية من CI بدون واجهة رسومية.

القيود: يعتمد على Node.js ولا يشغّل إلا مجموعات Postman JSON. بناء الاختبارات نفسه يبقى مرتبطًا بنظام Postman البيئي.

Apidog CLI: تشغيل السيناريوهات المرئية في CI

Apidog CLI هو حزمة npm باسم apidog-cli لتشغيل سيناريوهات الاختبار التي تبنيها في واجهة Apidog من المحطة الطرفية. أنشئ التدفق المرئي، واربط الطلبات، واستخرج المتغيرات، وأضف التأكيدات؛ ثم استخدم CLI لتشغيل السيناريو بدون واجهة رسومية.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

# انسخ الأمر الدقيق من تبويب CI/CD في السيناريو
apidog run -t <scenario_id> -e <env_id> -r cli

لا تخمّن معرف السيناريو أو البيئة. افتح سيناريو الاختبار في Apidog، وانتقل إلى تبويب CI/CD، ثم انسخ أمر apidog run المولّد بالمعرفات الصحيحة.

استخدم -r cli للحصول على تفاصيل التنفيذ وملخصه في المحطة الطرفية. وإذا كانت منصة CI تدعم تقارير JUnit، استخدم:

apidog run -t <scenario_id> -e <env_id> -r cli,junit

يعيد الأمر رمز خروج 0 عند نجاح جميع التأكيدات، ورمزًا غير صفري عند الفشل، لذلك يمكن استخدامه كبوابة مباشرة في pipeline. كما ينتج JSON منظمًا يتضمن agentHints.nextSteps، ما يجعله مناسبًا للتشغيل والقراءة بواسطة وكلاء البرمجة بالذكاء الاصطناعي.

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

القيود: يرتبط بالسيناريوهات المحفوظة في مشروع Apidog، لذلك ليس عميل HTTP عامًا مثل curl أو xh. Apidog ليس مفتوح المصدر، لكنه يوفر طبقة استخدام مجانية مع CLI.

للمزيد، راجع الدليل الكامل لـ Apidog CLI، ومرجع أمر apidog run، ودليل اختبار REST API من سطر الأوامر باستخدام Apidog CLI.

كيف تختار

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟	ملاحظات
curl	طلبات لمرة واحدة وسكريبتات	مثبت مسبقًا	نعم	شامل، والتأكيدات يدوية
HTTPie	طلبات يدوية قابلة للقراءة	`pip install httpie`	نعم	صياغة ودودة، يحتاج Python
xh	تجربة HTTPie أسرع	`brew install xh`	نعم	ملف Rust تنفيذي واحد
Hurl	اختبارات HTTP نصية	`brew install hurl`	نعم	`--test` مناسب لـ CI
Step CI	تدفقات YAML متعددة الخطوات	`npm i -g stepci`	نعم	REST/GraphQL/gRPC، يحتاج Node
k6	اختبار الحمل والأداء	`brew install k6`	نعم	سيناريوهات JavaScript وحدود نجاح
Newman	مجموعات Postman في CI	`npm i -g newman`	نعم	يشغّل Postman JSON بدون GUI
Apidog CLI	سيناريوهات مرئية تُشغّل بدون GUI	`npm i -g apidog-cli`	لا	يعتمد على رمز الخروج وتقارير JSON

ابدأ من الأداة الأقرب لحاجتك الحالية:

استخدم curl أو xh لفحص نقطة نهاية يدويًا.
انتقل إلى Hurl عندما تريد تحويل الفحص إلى اختبار نصي في التحكم بالإصدار.
استخدم Step CI عند الحاجة إلى تدفق تصريحي متعدد الخطوات.
استخدم k6 عندما يصبح السؤال متعلقًا بالحمل والأداء.
استخدم Newman إذا كانت اختباراتك موجودة أصلًا في Postman.
اختر Apidog CLI إذا أردت بناء سيناريو مرئي وتشغيله في أي بيئة بدون واجهة رسومية.

للمقارنة مع سير عمل headless كامل، راجع أدوات اختبار API بدون واجهة رسومية.

أين تؤتي الأدوات الخفيفة ثمارها؟

تفوز أدوات CLI عندما تريد البقاء في المحطة الطرفية، أو تشغيل الاختبارات في CI بدون تدخل بشري، أو تمكين وكيل AI من تشغيل الفحوصات وقراءة نتائجها.

يحافظ curl وxh على سرعة العمل اليدوي.
يحول Hurl وStep CI الطلبات إلى اختبارات قابلة للتكرار.
يختبر k6 الأداء تحت الحمل.
يشغّل Newman مجموعات Postman الحالية.
يربط Apidog CLI بين بناء السيناريو المرئي وتشغيله في المحطة الطرفية أو pipeline أو بواسطة وكيل.

صمّم السيناريو مرة واحدة في Apidog، ثم شغّله باستخدام apidog run حيثما تحتاج. نزّل Apidog، وابنِ سيناريو واحدًا، ثم أضف أمر التشغيل إلى إعداد CI لتجربة الدورة كاملة.

أفضل أدوات سطر الأوامر خفيفة الوزن لتوثيق الـ API

Yusuf Khalidd — Mon, 13 Jul 2026 04:25:05 +0000

لديك ملف OpenAPI وتريد توليد مستندات منه بدون إعداد خدمة، أو تسجيل الدخول إلى بوابة، أو إضافة خطوة بناء تسحب نصف حزمة npm. المطلوب بسيط: أمر واحد يقرأ المواصفات وينتج ملف Markdown أو صفحة HTML مستقلة يمكنك استضافتها في أي مكان.

جرّب Apidog اليوم

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

إذا كنت تبحث عن منصات توثيق بواجهات رسومية وميزات أوسع، راجع أفضل 10 أدوات لتوثيق واجهات برمجة تطبيقات REST. أما مرجع تنسيق الإدخال الذي تقرأه هذه الأدوات فهو مواصفات OpenAPI.

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

الأداة خفيفة الوزن عندما تقلل الاحتكاك بين ملف المواصفات وملف الوثائق النهائي:

تثبيت صغير: حزمة واحدة أو ثنائي واحد أفضل من سلسلة أدوات كاملة.
إعداد محدود: يجب أن تتمكن من تمرير openapi.yaml مباشرةً دون ملف إعدادات إضافي.
مخرج واضح: مواصفات في الداخل، وMarkdown أو HTML في الخارج.
قابلة للتشغيل في CI: لا واجهة رسومية، ولا خادم دائم، ولا تسجيل دخول للأدوات المفتوحة المصدر.

لخيارات أوسع تشمل منصات مستضافة، راجع أدوات توثيق واجهة برمجة التطبيقات المجانية.

Widdershins

يحول Widdershins ملفات OpenAPI 3 وSwagger 2 وAsyncAPI إلى Markdown. استخدمه عندما تريد ملفًا نصيًا قابلًا للحفظ في Git، أو المراجعة في Pull Request، أو إدراجه في موقع وثائق قائم.

التثبيت والتشغيل

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

لإنشاء الملف داخل خطوة CI:

widdershins openapi.yaml \
  --omitHeader \
  --language_tabs 'shell:curl' 'javascript:JavaScript' \
  -o docs/api.md

--omitHeader: يحذف مقدمة YAML من المخرج.
--language_tabs: يحدد لغات أمثلة الكود.

متى تستخدمه؟

استخدم Widdershins إذا كنت تحتاج إلى Markdown فقط وتخطط لعرضه لاحقًا عبر مولد موقع ثابت أو منصة وثائق.

القيود: لا ينشئ موقعًا أو واجهة تفاعلية. إنه محول مواصفات إلى Markdown، وليس عارض وثائق.

OpenAPI Generator

تشتهر OpenAPI Generator بتوليد حزم SDK، لكنها تتضمن أيضًا مولدات للوثائق. استخدمها إذا كنت تولد SDK ووثائق من نفس مواصفات OpenAPI.

التثبيت

npm install -g @openapitools/openapi-generator-cli

توليد Markdown

openapi-generator-cli generate \
  -g markdown \
  -i openapi.yaml \
  -o docs/

توليد HTML مستقل

openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/

يمكنك إضافته إلى package.json:

{
  "scripts": {
    "docs:markdown": "openapi-generator-cli generate -g markdown -i openapi.yaml -o docs",
    "docs:html": "openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html"
  }
}

ملاحظة عملية: غلاف npm ينزّل ملف JAR يعمل عبر JDK عند أول تشغيل، لذلك قد يكون أثقل من Widdershins في بيئة CI نظيفة.

Redocly CLI: إنشاء HTML بأمر واحد

إذا كان هدفك صفحة مرجعية HTML مستقلة، فإن Redocly CLI يوفر مسارًا مباشرًا. يبني build-docs ملف HTML واحدًا مبنيًا على Redoc، دون تشغيل خادم.

إنشاء الملف الافتراضي

npx @redocly/cli build-docs openapi.yaml

ينتج الأمر افتراضيًا الملف:

redoc-static.html

تحديد اسم ملف الإخراج

npx @redocly/cli build-docs openapi.yaml --output api.html

مثال مناسب لخط CI:

npx @redocly/cli build-docs openapi.yaml --output public/api.html

بعد ذلك، انشر محتوى public/ على أي استضافة ثابتة.

الأفضل لـ: صفحة مرجعية مصقولة وقابلة للمشاركة بسرعة.

القيود: المخرج صفحة HTML واحدة، وليس بوابة وثائق متعددة الصفحات. لمقارنة البدائل، راجع بدائل Redocly وبدائل Scalar.

Slate

Slate ليس محول OpenAPI مباشرًا؛ إنه مولد موقع ثابت لوثائق API المكتوبة يدويًا باستخدام Markdown. ينشئ التصميم التقليدي ذي الأعمدة الثلاثة: التنقل والمحتوى وعينات الكود.

يعمل Slate عبر Ruby وMiddleman، لذا فهو يحتاج إلى سلسلة أدوات أكبر من الخيارات الأخرى.

# بعد استنساخ مستودع Slate وتثبيت التبعيات
bundle exec middleman build

ينشئ الأمر موقعًا ثابتًا داخل:

build/

دمج Slate مع Widdershins

يمكنك استخدام الأداتين معًا:

widdershins openapi.yaml -o source/includes/_api.md
bundle exec middleman build

بهذا تحصل على محتوى Markdown مولّد من OpenAPI ضمن قالب Slate.

الأفضل لـ: فرق تريد تحرير الشرح والبنية يدويًا، مع الاستفادة من مواصفات OpenAPI كنقطة بداية.

القيود: يحتاج Ruby، ولا يقرأ OpenAPI وحده.

Apidog CLI: التصدير من مشروع API

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

يوفر apidog-cli أوامر للتعامل مع مشروع Apidog وتصدير مستنداته إلى Markdown أو HTML.

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

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

تصدير Markdown

apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md

تصدير HTML

apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html

إدارة موارد الوثائق

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

تعيد هذه الأوامر مخرجات JSON منظمة، لذلك يمكن تمريرها إلى خطوة أخرى في CI أو إلى نص برمجي.

مثال مبسط في CI:

apidog login --with-token "$APIDOG_TOKEN"

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format html \
  --output ./public/api.html

للتفاصيل الكاملة حول المصادقة والمشاريع والأوامر، راجع الدليل الكامل لـ Apidog CLI.

تنبيه مهم: Apidog ليس مفتوح المصدر، وCLI يتصل بمشروع مستضاف. كما أنه لا يحل محل أدوات فحص OpenAPI أو فرض دليل الأسلوب مثل Redocly وSpectral. قيمته الأساسية هي توفير مسار موحد من مشروع API إلى Markdown أو HTML قابل للنشر.

لمسار Markdown بشكل أكثر تفصيلًا، راجع مولد وثائق API مع تصدير Markdown.

كيف تختار؟

اختر وفقًا لشكل المدخلات والمخرج المطلوب:

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟	المخرجات
Widdershins	تحويل المواصفات إلى Markdown بسرعة	`npm i -g widdershins`	نعم، MIT	Markdown
OpenAPI Generator	وثائق إلى جانب حزم SDK	`npm i -g @openapitools/openapi-generator-cli`	نعم، Apache 2.0	Markdown أو HTML
Redocly CLI	صفحة HTML مصقولة واحدة	`npx @redocly/cli`	نعم، MIT وopen core	HTML مستقل
Slate	موقع وثائق منسق يدويًا	Ruby + Bundler	نعم، Apache 2.0	موقع ثابت
Apidog CLI	التصدير من مشروع مباشر	`npm i -g apidog-cli`	لا، طبقة مجانية	Markdown أو HTML

اختيار سريع

لديك ملف OpenAPI وتريد Markdown: استخدم Widdershins.
تريد صفحة HTML واحدة للنشر أو المشاركة: استخدم Redocly CLI.
تولد SDK بالفعل وتريد الوثائق من الأداة نفسها: استخدم OpenAPI Generator.
تريد تحرير المستندات يدويًا ضمن تصميم ثابت: استخدم Slate.
تعمل من مشروع API وتحتاج إلى التصدير وإدارة الوثائق: استخدم Apidog CLI.

للقائمة الأوسع من الخيارات المجانية، راجع أدوات توثيق API المجانية.

الخلاصة

اختر أصغر أداة تنتج المخرج الذي تحتاجه:

يغطي Widdershins معظم حالات توليد Markdown من مواصفات OpenAPI.
يغطي redocly build-docs معظم حالات إنشاء HTML مستقل بأمر واحد.
استخدم OpenAPI Generator إذا كان موجودًا أصلًا في خط توليد SDK.
استخدم Slate عندما تكون الكتابة والتحرير اليدويان جزءًا أساسيًا من الوثائق.
استخدم apidog-cli عندما تكون واجهة برمجة التطبيقات موجودة في مشروع وتريد تصدير Markdown أو HTML دون ربط عدة أدوات يدويًا.

إذا كانت واجهة برمجة التطبيقات لديك موجودة في مشروع Apidog، نزّل Apidog ثم شغّل apidog export ضمن CI لإعادة بناء الوثائق عند كل تغيير في الـ API.

أدوات سطر الأوامر مجانية ومفتوحة المصدر لتوثيق الـ API

Yusuf Khalidd — Mon, 13 Jul 2026 03:58:33 +0000

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

جرّب Apidog اليوم

هذه القائمة تركز على أدوات CLI مفتوحة المصدر تعمل مباشرةً مع ملفات OpenAPI أو Swagger. يمكنها إنتاج Markdown أو HTML ثابت أو موقع وثائق كامل تستضيفه بنفسك. جميع الأدوات المذكورة متاحة على GitHub بترخيص MIT أو Apache 2.0، ولا تحتاج إلى حساب لتشغيلها.

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

ملاحظة: يظهر Apidog قرب نهاية المقال كملاحظة جانبية فقط. ليس مفتوح المصدر؛ بل منصة تجارية بنموذج فريميوم. الغرض من ذكره هو توضيح الفجوة بين تصدير ملف مواصفات ثابت وإدارة مشروع API حي.

ما الذي يجعل أداة توثيق CLI مفتوحة المصدر؟

لا تعني «مفتوحة المصدر» أنها مجانية للتنزيل فقط. عند دمج الأداة في عملية البناء، تحقق من هذه النقاط:

ترخيص متساهل فعليًا

يتيح MIT وApache 2.0 استخدام الأداة وتعديلها وإعادة توزيعها تجاريًا. يضيف Apache 2.0 منحًا صريحًا لبراءات الاختراع، وهو ما قد تفضله بعض الفرق القانونية.
مخرجات قابلة للاستضافة الذاتية

يجب أن تنتج الأداة ملفات تملكها: Markdown، أو ملف HTML واحد، أو مجلد HTML/CSS/JS. عندها يمكنك النشر على GitHub Pages أو S3 أو Nginx بدون الاعتماد على خوادم بائع.
صيانة ومجتمع

تحقق من النشاط الأخير، والقضايا المفتوحة، والتفرعات النشطة. بعض الأدوات المؤرشفة ما زالت تعمل، لكنها قد تتطلب منك صيانة تفرع خاص بك لاحقًا.

ولمقارنة الخيارات المجانية، المفتوحة منها والفريميوم، راجع أدوات توثيق واجهة برمجة التطبيقات المجانية.

Redocly CLI

Redocly CLI هو مسار سريع لتحويل مواصفات OpenAPI إلى مرجع HTML مصقول ومكتفٍ ذاتيًا. سطر الأوامر ومحرك عرض Redoc مفتوحان المصدر بترخيص MIT، بينما تبقى بعض ميزات البوابة المستضافة ضمن المنتج المدفوع.

أنشئ ملف HTML واحدًا من المواصفات:

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

ثم اختبر الناتج محليًا:

open api-docs.html

أو انشره مباشرةً على أي استضافة ثابتة. لا يحتاج الملف الناتج إلى خادم تطبيق أو اتصال دائم بالإنترنت.

استخدمه عندما: تريد مرجع API نظيفًا من صفحة واحدة بأقل إعداد ممكن.

انتبه إلى: الناتج صفحة واحدة، وليس بوابة وثائق متعددة الصفحات. إذا كنت تقارن محركات العرض، راجع بدائل Redocly.

Widdershins

Widdershins محول بترخيص MIT يحول OpenAPI 3 وSwagger 2 وAsyncAPI إلى Markdown. لا يقدم موقعًا جاهزًا؛ بل يمنحك ملفات Markdown تستطيع تثبيتها في Git، ومراجعتها في pull requests، وتمريرها إلى أي مولد مواقع ثابت.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

لضبط الناتج:

widdershins openapi.yaml \
  --omitHeader \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md

--omitHeader: يحذف القسم التمهيدي.
--language_tabs: يحدد لغات أمثلة الكود.

استخدمه عندما: تريد Markdown قابلًا للتحكم في الإصدارات أو تريد تغذية Slate أو Docusaurus أو مولد موقع آخر.

انتبه إلى: Markdown هو الناتج النهائي؛ ستحتاج إلى أداة أخرى لتحويله إلى موقع معروض.

OpenAPI Generator

OpenAPI Generator مشروع مجتمعي بترخيص Apache 2.0، تفرع من Swagger Codegen في 2018. يشتهر بتوليد SDKs، لكنه يوفر أيضًا مولدات للوثائق.

ثبّت الواجهة ثم أنشئ Markdown أو HTML:

npm install -g @openapitools/openapi-generator-cli

# مجلد يحتوي ملفات Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# صفحة HTML مستقلة
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

يمكنك وضع هذه الأوامر في CI، ثم نشر المجلد الناتج كأحد مخرجات البناء:

openapi-generator-cli generate -g html2 -i openapi.yaml -o public/

استخدمه عندما: تريد أداة واحدة لتوليد SDKs والوثائق من نفس مواصفات OpenAPI.

انتبه إلى: غلاف npm ينزّل ملف Java JAR في التشغيل الأول، لذا ليس أداة ثنائية خفيفة بالكامل. مخرجات القوالب أساسية مقارنةً بمحركات العرض المتخصصة.

Swagger Codegen

Swagger Codegen هو المولد الأصلي من فريق Swagger، بترخيص Apache 2.0، وما زال يُصان بواسطة SmartBear. يوفّر مولد html لمرجع ثابت من صفحة واحدة، وdynamic-html لموقع تفاعلي صغير.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

إذا كان فريقك يستخدم Swagger Codegen بالفعل لتوليد المكونات أو العملاء، فإن استخدامه للوثائق يحافظ على سلسلة أدوات موحدة.

استخدمه عندما: يكون نظام Swagger البيئي جزءًا من إعدادك الحالي.

انتبه إلى: يعتمد على Java ويتطور بوتيرة أبطأ من OpenAPI Generator. للإعدادات الجديدة، يكون OpenAPI Generator غالبًا الخيار الأكثر نشاطًا؛ بينما يتفوق Swagger Codegen في الاستمرارية للفرق التي اعتمدته مسبقًا.

Docusaurus مع إضافة OpenAPI

إذا كنت تحتاج إلى بوابة وثائق كاملة بدل صفحة HTML واحدة، فاستخدم Docusaurus بترخيص MIT. يعرض Docusaurus ملفات Markdown وMDX، بينما تحول إضافة docusaurus-openapi-docs مواصفات OpenAPI إلى صفحات MDX داخل الموقع.

ابدأ مشروعًا جديدًا:

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

بعد إعداد الإضافة ومسار ملف المواصفات، ولّد صفحات API:

npm run docusaurus gen-api-docs all
npm run build

ينتج build موقعًا ثابتًا في مجلد build/ يمكنك نشره على GitHub Pages أو S3 أو أي CDN.

استخدمه عندما: تحتاج إلى إصدارات متعددة، بحث، شريط تنقل جانبي، وأدلة مكتوبة يدويًا بجانب المرجع المولد.

انتبه إلى: هذا هو الإعداد الأثقل في القائمة؛ فهو موقع React كامل مع خطوة بناء. إذا كنت تحتاج فقط إلى مرجع API، فـ Redocly CLI أقصر بكثير.

Slate

Slate هو تخطيط وثائق API الكلاسيكي بثلاثة أعمدة: تنقل على اليسار، محتوى في الوسط، وأمثلة كود على اليمين. يعمل بترخيص Apache 2.0 ويستخدم Middleman، لذلك يحتاج إلى Ruby وBundler.

لا يقرأ Slate مواصفات OpenAPI مباشرةً. بدلاً من ذلك، تكتب Markdown يدويًا أو تولده باستخدام Widdershins، ثم تبني الموقع:

# بعد استنساخ تفرع Slate وتشغيل bundle install
bundle exec middleman build

سيظهر الموقع الثابت في مجلد:

build/

مسار عملي شائع:

widdershins openapi.yaml -o source/index.html.md
bundle exec middleman build

استخدمه عندما: تريد وثائق سردية منتقاة يدويًا وتحكمًا تحريريًا كاملًا بتخطيط ثلاثي الأعمدة.

انتبه إلى: المستودع الأصلي مؤرشف، رغم أن التفرعات ما زالت نشطة. كما أن سلسلة Ruby أثقل من تشغيل أمر npx واحد.

Apidog CLI: ملاحظة جانبية، وليس إدخالًا مفتوح المصدر

الأدوات السابقة تغطي التحويل أو العرض أو الاستضافة. لكن عند التعامل مع مشروع API حي يحتوي على نقاط نهاية ومخططات وأمثلة تُحدَّث باستمرار، قد تحتاج إلى ربط محول وعارض واستضافة بنفسك والحفاظ على تزامنها.

هنا يظهر apidog-cli كخيار مختلف. يجب أن يكون الفرق واضحًا: Apidog ليس مفتوح المصدر؛ إنه منتج فريميوم وسطر الأوامر يعمل مع مشروع مستضاف، لا مع مواصفات محلية فقط.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

يمكنك استخدام التصدير ضمن CI لإعادة بناء الوثائق عند تحديث المشروع. كما يوفر apidog doc وapidog docs-site إدارة موارد الوثائق من خلال سكربتات.

للتفاصيل، راجع الدليل الكامل لـ Apidog CLI ومولد وثائق API مع تصدير Markdown.

الحد الفاصل بسيط:

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

كيف تختار

طابق الأداة مع نوع المخرجات التي تحتاجها وسير العمل الحالي لفريقك:

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟	المخرجات
Redocly CLI	صفحة HTML مصقولة واحدة	`npx @redocly/cli`	نعم، MIT	HTML مستقل
Widdershins	تحويل المواصفات إلى Markdown قابل للتثبيت	`npm i -g widdershins`	نعم، MIT	Markdown
OpenAPI Generator	وثائق وSDKs من أداة واحدة	`npm i -g @openapitools/openapi-generator-cli`	نعم، Apache 2.0	Markdown أو HTML
Swagger Codegen	فرق تعتمد Swagger Codegen مسبقًا	`npm i -g swagger-codegen-cli`	نعم، Apache 2.0	HTML
Docusaurus + OpenAPI plugin	بوابة وثائق كاملة مستضافة ذاتيًا	`npx create-docusaurus`	نعم، MIT	موقع ثابت
Slate	وثائق منتقاة يدويًا بثلاثة أعمدة	Ruby + Bundler	نعم، Apache 2.0	موقع ثابت
Apidog CLI	التصدير من مشروع API حي	`npm i -g apidog-cli`	لا، فريميوم	Markdown أو HTML

اختيار سريع:

استخدم Redocly CLI لمرجع HTML بسيط قابل للمشاركة.
استخدم Widdershins عندما يكون Markdown هو الأصل الذي تريد مراجعته وتثبيته.
استخدم OpenAPI Generator إذا كنت تولد SDKs ووثائق من نفس المواصفات.
استخدم Swagger Codegen للاستمرارية ضمن سلسلة Swagger الحالية.
استخدم Docusaurus لبوابة وثائق كاملة تحتوي أدلة وإصدارات.
استخدم Slate عندما يكون التحكم التحريري والتوثيق اليدوي أهم من التوليد المباشر.
استخدم Apidog CLI فقط إذا كنت تقبل نموذجًا مستضافًا وفريميوم لتصدير مشروع API حي.

لخيارات مجانية أوسع، راجع أدوات توثيق API المجانية.

خلاصة

يعتمد اختيار أداة توثيق CLI مفتوحة المصدر على ثلاثة عوامل: الترخيص، نوع المخرجات، ومكان وجود مصدر الحقيقة لواجهة API.

اختر أصغر أداة تنتج ما تحتاجه:

Redocly CLI لصفحة HTML واحدة.
Widdershins لـ Markdown.
OpenAPI Generator أو Swagger Codegen للوثائق بجانب SDKs.
Docusaurus لبوابة وثائق.
Slate للصفحات المنتقاة يدويًا.

إذا كانت واجهة API لديك موجودة في مشروع مُدار بدل ملف منفرد، وتفضل تصدير الوثائق بدل ربط عدة أدوات، يمكنك تنزيل Apidog وتجربة apidog export ضمن CI. فقط تذكّر أن هذه المنصة فريميوم وليست أداة مفتوحة المصدر.

أدوات CLI مجانية ومفتوحة المصدر للتطوير

Yusuf Khalidd — Mon, 13 Jul 2026 03:42:01 +0000

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

جرّب Apidog اليوم

ستبني في هذا المقال مجموعة أدوات عملية تغطي دورة العمل الأساسية: إرسال طلبات HTTP، تحليل JSON، اختبار التدفقات، أتمتة GitHub، كشف خادم محلي للإنترنت، وإصدار الكود. لكل أداة ستجد الترخيص والمستودع ومثالًا قابلًا للتشغيل مباشرة.

ما الذي يجعل أداة CLI مفتوحة المصدر فعلًا؟

ليست كل أداة مجانية أداة مفتوحة المصدر. استخدم هذه القائمة للتحقق قبل اعتماد أي أداة في مشروعك:

تحقق من الترخيص

ابحث عن ترخيص معتمد من OSI مثل MIT أو Apache 2.0 أو BSD أو GPL. هذه التراخيص تتيح لك الاستخدام والتعديل والاستضافة الذاتية ضمن شروطها.
تحقق من المصدر وسجل الصيانة

يجب أن يكون المصدر متاحًا على GitHub أو منصة مكافئة. راجع ملف LICENSE، والإصدارات، والمشاكل المفتوحة، وسجل الالتزامات.
تجنب الارتباط الإجباري

لا ينبغي أن تتطلب الأداة حسابًا أو خادمًا مستأجرًا لتعمل في السيناريو الأساسي. إذا كانت تعتمد على خدمة، فاعرف ما إذا كان يمكنك تشغيل المكونات بنفسك.

النجوم ليست معيارًا كافيًا. أداة هادئة ومستقرة بترخيص MIT أو Apache قد تكون خيارًا أفضل من أداة شائعة تقيّد الاستخدام التجاري أو تمنع الاستضافة الذاتية.

curl: عميل HTTP الأساسي

تُعد curl نقطة البداية لمعظم عمليات HTTP في الطرفية. تدعم بروتوكولات عديدة، وتأتي مثبتة مسبقًا في معظم الأنظمة، وتناسب السكربتات وبيئات CI. وهي مرخصة تحت ترخيص curl المتساهل، ومصدرها متاح على github.com/curl/curl.

أرسل طلب POST مصادقًا

curl -s -X POST https://api.github.com/repos/curl/curl/issues \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test issue","body":"Filed from curl"}'

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

أمر متاح تقريبًا في كل بيئة.
طلبات قابلة للتشغيل داخل shell scripts.
تنفيذ سريع في CI/CD.
تحكم كامل في الرؤوس والجسم وطرق الطلب.

القيد العملي: إخراج curl خام، لذلك ستحتاج غالبًا إلى jq لتحليل JSON.

HTTPie: طلبات HTTP مقروءة أثناء التصحيح

يوفر HTTPie صياغة أبسط للطلبات التفاعلية. الطلبات مقروءة، وأجسام JSON تُنشأ تلقائيًا، والاستجابة تظهر منسقة وملونة. الأداة مرخصة تحت BSD-3-Clause، ومصدرها موجود على github.com/httpie/cli.

التثبيت والاستخدام

pip install httpie

http POST httpbin.org/post name=apidog role=platform

في هذا المثال، تتحول القيم:

name=apidog
role=platform

إلى جسم JSON تلقائيًا. استخدم HTTPie عند استكشاف API أو تصحيح طلب يدويًا، خصوصًا عندما تريد رؤية الاستجابة بشكل واضح دون إضافة خيارات كثيرة.

القيد العملي: يعتمد على Python، لذلك قد يكون curl أخف في صور CI الصغيرة أو الحاويات محدودة الحجم.

jq: استخرج البيانات التي تحتاجها من JSON

تعيد معظم APIs بيانات JSON، وjq هي أداة الطرفية المناسبة للتصفية والاستخراج وإعادة التشكيل. الأداة مرخصة تحت MIT ومصدرها متاح على github.com/jqlang/jq.

استخرج حقولًا محددة من استجابة API

curl -s https://api.github.com/repos/jqlang/jq \
  | jq '{name: .name, stars: .stargazers_count, license: .license.spdx_id}'

بدلًا من التعامل مع الاستجابة كاملة، ستحصل على كائن صغير بالشكل الذي تحتاجه:

{
  "name": "jq",
  "stars": 0,
  "license": "MIT"
}

قيمة stars في المثال تعتمد على وقت تشغيل الطلب.

استخدم jq في خطوط الأنابيب:

curl -s https://api.github.com/repos/jqlang/jq \
  | jq -r '.html_url'

القيد العملي: صياغة jq مختصرة وقوية، وقد تصبح التحويلات المعقدة صعبة القراءة. لكن لاستخراج الحقول والتصفية اليومية، ستغطي الأساسيات معظم احتياجاتك.

gh: أتمتة GitHub من الطرفية

تجلب gh عمليات GitHub إلى الطرفية: المشاكل، وطلبات السحب، والإصدارات، وGitHub Actions، وREST وGraphQL APIs. الأداة مكتوبة بلغة Go، ومرخصة تحت MIT، ومصدرها على github.com/cli/cli.

اجلب أحدث إصدار لمستودع

gh api repos/cli/cli/releases --jq '.[0].tag_name'

يستخدم هذا الأمر مصادقة gh الحالية، لذلك لا تحتاج إلى تمرير رمز وصول يدويًا كما تفعل عادة مع curl.

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

إنشاء أو إدارة issues وpull requests.
تشغيل أو فحص GitHub Actions.
استدعاء GitHub API من سكربتات الإصدار.
تنفيذ أتمتة مرتبطة بالمستودعات.

القيد العملي: الأداة مخصصة لـ GitHub فقط. للتعامل مع GitLab أو Gitea، استخدم الواجهة الخاصة بهما أو curl مباشرة ضد API.

Hurl: اختبارات HTTP قابلة للحفظ في Git

تتيح لك Hurl تعريف طلبات HTTP واختباراتها في ملفات نصية بسيطة. يمكنك تأكيد رموز الحالة والرؤوس ومسارات JSON، ثم حفظ هذه الملفات بجانب كود التطبيق. Hurl مكتوبة بلغة Rust، ومرخصة تحت Apache 2.0، ومصدرها على github.com/Orange-OpenSource/hurl.

أنشئ اختبارًا في ملف `repo.hurl`

GET https://api.github.com/repos/Orange-OpenSource/hurl

HTTP 200
[Asserts]
jsonpath "$.name" == "hurl"
jsonpath "$.stargazers_count" > 1000

شغّل الاختبار:

hurl --test repo.hurl

يعيد Hurl الرمز 0 عند نجاح جميع التأكيدات، ورمزًا غير صفري عند فشل أي اختبار. لذلك يمكنك إضافته مباشرة إلى CI:

hurl --test tests/*.hurl

استخدم Hurl لاختبارات التكامل القابلة للمراجعة داخل pull requests. وهو مناسب عندما تريد ملفات اختبار بسيطة يمكن للفريق قراءتها وتعديلها دون إطار اختبار كامل.

القيد العملي: يركز Hurl على اختبار تدفقات HTTP، وليس بديلًا كاملًا لاختبار العقود أو اختبار الحمل. إذا كنت تعمل ضمن سير عمل تطوير API المعتمد على المواصفات أولًا، فحافظ على OpenAPI كمصدر موثوق وأضف ملفات Hurl لاختبار السلوك الفعلي.

cloudflared: اكشف خادمك المحلي بعنوان عام

عند اختبار webhooks أو تطبيقات الجوال أو العروض التوضيحية، تحتاج أحيانًا إلى عنوان HTTPS عام يشير إلى خادم يعمل محليًا. يوفر cloudflared وضع نفق سريع ينشئ عنوانًا مؤقتًا من نطاق trycloudflare.com دون حساب. الأداة مكتوبة بلغة Go، ومرخصة تحت Apache 2.0، ومصدرها على github.com/cloudflare/cloudflared.

اكشف خادمًا يعمل على المنفذ 3000

cloudflared tunnel --url http://localhost:3000

سيطبع الأمر عنوان HTTPS عامًا يعيد التوجيه إلى:

http://localhost:3000

استخدمه لتسجيل عنوان webhook مؤقتًا أو لمشاركة نسخة تطوير مع شخص آخر.

إذا كنت تفضل بيئة npm، فإن localtunnel المرخصة تحت MIT توفر بديلًا مشابهًا:

npx localtunnel --port 3000

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

git: اجعل اختبارات API جزءًا من تاريخ المشروع

Git ليس مجرد خلفية لواجهة رسومية؛ واجهة سطر الأوامر هي المكان الذي تستخدم فيه rebase وbisect وhooks والتحكم الدقيق في staging. كل ملف OpenAPI، واختبار Hurl، وسكربت curl يجب أن يعيش في مستودع Git. Git مرخص تحت GPLv2 ومصدره على github.com/git/git.

شغّل اختبارات Hurl قبل كل commit

أنشئ hook محليًا:

echo 'hurl --test *.hurl' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

الآن، سيفشل git commit إذا فشل أحد اختبارات Hurl.

ملاحظة: ملفات hooks داخل .git/hooks لا تُشارك تلقائيًا مع الفريق. إذا أردت توحيدها، احتفظ بسكربتات hooks في المستودع واضبط core.hooksPath داخل إعدادات المشروع.

القيد العملي: Git نظام تحكم في الإصدارات، وليس منصة استضافة. اختيار GitHub أو GitLab أو Gitea هو قرار منفصل.

ملاحظة صادقة: أين تتناسب Apidog؟

Apidog ليس مفتوح المصدر، لذلك لا ينتمي إلى قائمة أدوات OSS. إنه منتج تجاري يوفّر طبقة مجانية. الفرق العملي هو أن الأدوات السابقة تؤدي مهامًا متخصصة، بينما تحتاج أنت إلى تجميعها وإدارة إعداداتها: curl للطلبات، وjq للبيانات، وHurl للاختبارات، وأدوات منفصلة للمحاكاة والتوثيق والمتغيرات.

يجمع Apidog التصميم والاختبار والمحاكاة والتوثيق في مساحة عمل واحدة. كما تنقل apidog-cli أجزاء من هذا التدفق إلى الطرفية.

npm install -g apidog-cli

بحسب سير العمل المستخدم، يمكن لـ apidog-cli تشغيل سيناريوهات الاختبار وإدارة نقاط النهاية والمخططات وتوقعات المحاكاة واستيراد أو تصدير OpenAPI، مع إخراج JSON منظم مناسب للسكربتات ووكلاء الذكاء الاصطناعي. كما أن apidog run يعيد الرمز 0 عند النجاح ورمزًا غير صفري عند الفشل، ما يجعله مناسبًا لـ CI مثل Hurl.

الاختيار هنا واضح:

اختر أدوات OSS المتخصصة إذا كانت الأولوية للتحكم الكامل والوصول إلى المصدر وتقليل الارتباط.
اختر منصة متكاملة إذا أردت تقليل عدد الأدوات والبنية التحتية التي تديرها.

إذا اخترت مسار CLI، راجع دليل تثبيت Apidog CLI لمعرفة خطوات المصادقة والأوامر الأولى.

كيف تختار الأداة المناسبة؟

استخدم عدة أدوات معًا بدل البحث عن أداة واحدة لكل شيء:

الأداة	الأفضل لـ	التثبيت	مفتوحة المصدر؟	ملاحظات
curl	طلبات محمولة وسكربتات	مثبتة مسبقًا غالبًا	نعم (curl/نوع MIT)	متاحة في معظم الأنظمة
HTTPie	تصحيح أخطاء تفاعلي	`pip install httpie`	نعم (BSD-3-Clause)	JSON وإخراج ملون
jq	تحليل استجابات JSON	مدير حزم أو ثنائي	نعم (MIT)	أساسية لخطوط الأنابيب
gh	أتمتة GitHub	مدير حزم أو ثنائي	نعم (MIT)	مخصصة لـ GitHub
Hurl	اختبارات HTTP قابلة للإصدار	ثنائي واحد	نعم (Apache 2.0)	رمز خروج غير صفري عند الفشل
cloudflared	أنفاق عامة مؤقتة	ثنائي واحد	نعم (Apache 2.0)	النفق السريع لا يحتاج حسابًا
git	التحكم في الإصدارات	مثبتة مسبقًا غالبًا	نعم (GPLv2)	أساس بقية الأدوات
apidog-cli	سير عمل API متكامل	`npm i -g apidog-cli`	لا، طبقة مجانية	تصميم واختبار ومحاكاة وتوثيق

القاعدة العملية:

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

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

الخلاصة

تمنحك أدوات curl وHTTPie وjq وgh وHurl وcloudflared وGit مجموعة عملية ومفتوحة المصدر لتطوير APIs والعمل الخلفي. ابدأ بالحد الأدنى:

استخدم curl أو HTTPie لإرسال الطلبات.
أضف jq لمعالجة JSON.
أضف Hurl عندما تحتاج إلى اختبارات قابلة للتشغيل في CI.
احفظ المواصفات والاختبارات والسكريبتات في Git.
استخدم cloudflared عندما تحتاج إلى URL عام لخادمك المحلي.

إذا كنت تبني تدفقات عمل تعتمد على الوكلاء، فاجعل مخرجات أدواتك منظمة وقابلة للقراءة آليًا، خصوصًا JSON. لمزيد من التفاصيل، راجع مقال مساعدي الذكاء الاصطناعي في تطوير واجهات برمجة التطبيقات.

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

أدوات CLI مجانية مفتوحة المصدر لإدارة الـ API

Yusuf Khalidd — Fri, 10 Jul 2026 10:11:50 +0000

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

جرّب Apidog اليوم

تكون زاوية المصدر المفتوح مهمة عندما تستضيف البوابة بنفسك. فالترخيص يحدد ما إذا كان بإمكانك تشغيل الأداة وتفريعها وشحنها دون تكلفة لكل مستخدم. تستخدم معظم الأدوات أدناه تراخيص Apache 2.0 أو MPL 2.0، ما يعني أن المصدر متاح ويمكنك تشغيله على بنيتك التحتية.

يغطي هذا الدليل بوابات API مفتوحة المصدر مع سير عمل عملي من الطرفية:

Kong Gateway OSS مع decK
Tyk
KrakenD Community Edition
Apache APISIX
Gravitee

ستجد لكل أداة: الترخيص، ودور CLI الفعلي، وأوامر قابلة للنسخ. لمقارنة أوسع للمنصات، راجع أدوات إدارة واجهة برمجة التطبيقات مفتوحة المصدر. ومن المفيد أيضًا مراجعة نص ترخيص Apache 2.0 الرسمي.

ملاحظة: يظهر Apidog في نهاية المقال، لكنه ليس أداة مفتوحة المصدر. إنه منتج تجاري يوفر طبقة مجانية، ويُذكر هنا كأداة مكملة للبوابات وليس كبديل مفتوح المصدر عنها.

ما الذي يجعل CLI لإدارة API مفتوح المصدر فعلًا؟

استخدم هذه القائمة قبل اعتماد أي بوابة.

1. تحقق من الترخيص

ابحث عن ترخيص مثل Apache 2.0 أو MIT أو MPL 2.0 على مشروع البوابة الأساسي، وليس فقط على SDK أو مكتبة عميل.

Apache 2.0: يسمح بالاستضافة الذاتية والتعديل والتوزيع.
MPL 2.0: ترخيص copyleft على مستوى الملف؛ يجب أن تبقى تعديلات ملفات MPL مفتوحة، بينما يمكن أن تبقى المكونات المنفصلة احتكارية.
Source Available أو BSL: لا يعادلان تلقائيًا المصدر المفتوح؛ اقرأ ملف LICENSE في المستودع.

2. تأكد من إمكانية الاستضافة الذاتية

يجب أن تعمل البوابة على بنيتك التحتية دون الاعتماد على خادم ترخيص خارجي. يجب أن تتحكم أنت في مستوى البيانات وتشغيله.

3. اختبر سير عمل Git وCI

ابحث عن مشروع نشط وواجهة CLI قابلة للاستخدام. الهدف هو أن تتمكن من:

تعريف التكوين في ملفات.
حفظه في Git.
مراجعته عبر Pull Request.
التحقق منه في CI.
نشره من خط أنابيب آلي.

للسياق الأوسع، راجع ما تغطيه إدارة واجهة برمجة التطبيقات بالفعل.

Kong Gateway OSS مع decK

Kong Gateway OSS هو إصدار Kong المرخص تحت Apache 2.0. تُدار البوابة عبر Admin API، لكن أداة CLI الأساسية للتكوين التصريحي هي decK.

استخدم decK لتصدير الحالة الحالية إلى YAML، مراجعة التغييرات، ثم مزامنة التكوين مع البوابة.

# تصدير إعداد Kong الحالي إلى ملف
deck gateway dump -o kong.yaml

# مزامنة الإعداد التصريحي مع البوابة
deck gateway sync kong.yaml

سير عمل مقترح

صدّر الإعداد الحالي إلى kong.yaml.
أضف الملف إلى Git.
عدّل المسارات أو الخدمات أو المكونات الإضافية.
راجع الفرق في Pull Request.
شغّل deck gateway sync kong.yaml من CI أو من بيئة النشر.

الأفضل لـ: فرق تستخدم Kong وتريد إدارة المسارات والمكونات الإضافية كبنية تحتية ككود (IaC).

القيود: decK خاص بـ Kong ويركز على التكوين، لا على التوثيق أو الاختبار. كما أن تشغيل Kong الكامل أثقل من بوابة ثنائية واحدة.

Tyk

بوابة Tyk مفتوحة المصدر بموجب MPL 2.0. تدعم البوابة الأساسية المكتوبة بـ Go بروتوكولات REST وGraphQL وTCP وgRPC.

أمر CLI العملي الشائع هو أداة التجميع المضمنة في ملف البوابة الثنائي منذ الإصدار 2.8. استخدمها لتعبئة مكونات middleware المخصصة في حزمة يمكن للبوابة تحميلها.

# إنشاء حزمة مكونات إضافية من manifest وملفات middleware
tyk bundle build -o bundle.zip

متى تستخدمه؟

استخدم Tyk عندما تحتاج إلى مكونات إضافية مخصصة للمصادقة أو التحويل أو منطق middleware، وتريد عملية تعبئة قابلة للتكرار في CI.

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

القيود: CLI يركز على التجميع، وليس على إدارة تعريفية كاملة للبوابة. الكثير من إدارة Tyk يتم عبر لوحة التحكم المدفوعة أو Gateway API مباشرة.

KrakenD Community Edition

KrakenD بوابة عالية الأداء وعديمة الحالة (stateless). يوفر إصدار المجتمع الميزات الأساسية تحت Apache 2.0.

الميزة الرئيسية هنا هي عدم وجود قاعدة بيانات: ملف التكوين هو المصدر الوحيد للحقيقة. هذا يجعل KrakenD مناسبًا لـ Git وCI مباشرة.

# التحقق من صحة الإعداد وتنفيذ lint قبل النشر
krakend check -c krakend.json --lint

# تشغيل البوابة باستخدام الإعداد نفسه
krakend run -c krakend.json

سير عمل مقترح

# 1. تحقق من الإعداد في CI
krakend check -c krakend.json --lint

# 2. انشر فقط إذا نجح التحقق
krakend run -c krakend.json

يمكنك استخدام التكوين المرن عبر FC_ENABLE=1 لتقسيم الإعدادات الكبيرة إلى قوالب وملفات متغيرات، ما يساعد على إبقاء إعدادات البيئات المختلفة قابلة لإعادة الاستخدام.

الأفضل لـ: بوابة تعريفية بالكامل، حيث يكون ملف التكوين هو المصدر الوحيد للحقيقة.

القيود: لا يوفر إصدار المجتمع واجهة إدارة أو استمرارية مدمجة. يجب تعريف السلوك في التكوين بدلًا من تغييره من لوحة تحكم.

Apache APISIX

Apache APISIX مشروع رفيع المستوى تابع لمؤسسة Apache Software Foundation ومرخص تحت Apache 2.0. هذا مهم لأن إصدار OSS هو المشروع الأساسي نفسه، وليس نسخة مجتمع محدودة من منتج بائع.

يوفر APISIX:

CLI لعمليات دورة الحياة.
Admin API من نوع REST لإدارة المسارات والمكونات الإضافية.
إعادة تحميل للتكوين دون قطع الاتصالات.

# عرض أوامر التحكم المتاحة
apisix help

# تشغيل البوابة
apisix start

# إعادة تحميل التكوين بعد التعديل
apisix reload

تكون Admin API مرتبطة بـ 127.0.0.1 افتراضيًا. استخدم apisix reload لالتقاط تغييرات التكوين دون إعادة تشغيل كاملة.

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

القيود: عادةً ما تعيش إعدادات التوجيه في Admin API بدلًا من دفعة CLI تعريفية واحدة. إذا أردت سير عمل “التكوين في Git”، ستحتاج إلى أتمتة استدعاءات Admin API أو استخدام أداة إضافية مثل ADC من APISIX.

Gravitee

منصة Gravitee الأساسية لإدارة API مفتوحة المصدر تحت Apache 2.0. وهي أكثر من مجرد بوابة، إذ يشمل إصدار المجتمع:

بوابة APIM لوقت التشغيل.
APIM REST API للإدارة.
وحدة تحكم APIM.

تتوفر بعض ميزات Enterprise، مثل واجهات برمجة التطبيقات غير المتزامنة الأصلية للأحداث، في الإصدار المدفوع. لكن جوهر REST قابل للاستضافة الذاتية ومفتوح المصدر.

لتشغيل البوابة ذاتيًا باستخدام Docker:

# تشغيل حاوية Gravitee APIM Gateway ذاتيًا
docker run --name gravitee-gateway -p 8082:8082 graviteeio/apim-gateway:latest

تعتمد الإدارة اليومية عادةً على REST Management API ووحدة التحكم. يوجد أيضًا graviteeio-cli من المجتمع على GitHub لتغليف واجهة الإدارة وأتمتة الإجراءات، لكنه ليس أداة رسمية من الطرف الأول؛ تحقق من نشاط صيانته قبل اعتماده في الإنتاج.

الأفضل لـ: فرق تريد طبقة إدارة OSS كاملة تضم بوابة ووحدة تحكم وواجهة إدارة قابلة للبرمجة.

القيود: سطح الأتمتة الأساسي هو REST API، وليس CLI رسمية موحدة. CLI المجتمعية قد تسد الفجوة، لكن مسؤولية صيانتها تقع عليك.

مكان Apidog ولماذا لا يندرج ضمن أدوات المصدر المفتوح

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

تتعامل البوابات مع حركة المرور والمسارات والمكونات الإضافية، لكنها لا تغطي بالضرورة:

تصميم مخطط API.
اختبار نقاط النهاية.
إنشاء التوثيق.
محاكاة الاستجابات قبل توفر الواجهة الخلفية.

غالبًا ما يتطلب تجميع هذه المهام أدوات منفصلة مثل Spectral وopenapi-generator وخادم mock وNewman. يجمع Apidog التصميم والاختبار والمحاكاة والتوثيق في مساحة عمل واحدة، ويوفر apidog-cli لتنفيذ هذه المهام من الطرفية.

# تثبيت Apidog CLI والمصادقة
npm install -g apidog-cli
apidog login --with-token <TOKEN>

# تشغيل سيناريو اختبار في CI
# ينتهي الأمر برمز غير صفري عند الفشل
apidog run

تنتج CLI مخرجات JSON منظمة تتضمن agentHints.nextSteps، ما يجعلها مناسبة لخطوط CI ومسارات عمل وكلاء الذكاء الاصطناعي. لمزيد من التفاصيل، راجع إدارة واجهات برمجة التطبيقات دون مغادرة وكلاء الذكاء الاصطناعي.

كما تدعم الأداة استيراد وتصدير OpenAPI، وتشغيل السيناريوهات، وتشغيل المحاكاة من CLI. راجع الدليل الكامل لـ Apidog CLI لمعرفة مجموعات الأوامر.

فكّر في Apidog كطبقة متكاملة للتصميم والاختبار بجانب بوابة OSS مستضافة ذاتيًا، وليس كبديل عنها.

كيفية الاختيار

الأداة	الأفضل لـ	الترخيص	مفتوح المصدر؟	CLI / الأمر
Kong Gateway OSS + decK	تكوين Kong كبنية تحتية ككود في Git	Apache 2.0	نعم	`deck gateway sync`
Tyk	تجميع المكونات الإضافية المخصصة ودعم بروتوكولات متعددة	MPL 2.0	نعم	`tyk bundle build`
KrakenD Community Edition	بوابة عديمة الحالة وتكوين ككود	Apache 2.0	نعم	`krakend run`
Apache APISIX	توجيه ديناميكي عالي الإنتاجية	Apache 2.0	نعم، مشروع ASF	`apisix start` / `apisix reload`
Gravitee	طبقة إدارة OSS كاملة مع وحدة تحكم	Apache 2.0	نعم، في الإصدار الأساسي	Docker CLI / REST API
Apidog CLI	تصميم واختبار ومحاكاة وتوثيق في مكان واحد	فريميوم	لا	`apidog run`

اختر بناءً على سير العمل الفعلي، لا على عدد نجوم GitHub فقط:

تستخدم Kong بالفعل؟ ابدأ بـ decK.
تريد بوابة بلا قاعدة بيانات وملف إعداد واحد؟ اختر KrakenD.
تحتاج تغييرات توجيه ديناميكية في وقت التشغيل؟ اختر APISIX.
تريد بوابة ووحدة تحكم وواجهة إدارة كاملة؟ استخدم Gravitee.
تحتاج طبقة موحدة لتصميم API واختبارها ومحاكاتها؟ أضف Apidog بجانب بوابتك.

للمقارنة الأوسع، راجع أفضل أدوات إدارة واجهة برمجة التطبيقات لعام 2026 وإدارة واجهة برمجة التطبيقات بدون رأس.

خلاصة

إدارة API مفتوحة المصدر من الطرفية ناضجة وقابلة للتطبيق في الإنتاج. Kong Gateway OSS مع decK وTyk وKrakenD CE وApache APISIX وGravitee كلها قابلة للاستضافة الذاتية، وتستخدم تراخيص Apache 2.0 أو MPL 2.0، وتوفر مسارًا للتشغيل والأتمتة من الطرفية.

ابدأ بتحديد نموذج النشر الذي تحتاجه:

تكوين تعريفـي في Git.
تحديثات ديناميكية وقت التشغيل.
مكونات إضافية مخصصة.
طبقة إدارة كاملة.
أدوات تصميم واختبار مكملة للبوابة.

للتصميم والاختبار والمحاكاة والتوثيق، يمكنك تنزيل Apidog وتشغيل apidog run ضمن خط CI بجانب بوابة OSS التي تختارها.

DEV Community: Yusuf Khalidd

كيفية منع وكلاء الذكاء الاصطناعي من تعطيل واجهات برمجة التطبيقات العاملة

لماذا يكون وصول الوكيل للكتابة خطيرًا افتراضيًا؟

الحل: إنشاء فرع AI معزول

1. ثبّت Apidog CLI وسجّل الدخول

2. أنشئ فرع AI من main

استورد الموارد المطلوبة فقط

نفّذ التعديلات داخل الفرع ثم راجع الفروقات

أرسل التغييرات عبر طلب دمج

الدمج المباشر إلى فرع غير محمي

إنشاء طلب دمج إلى main محمي

نظّف الفروع المدمجة أو المهجورة

قواعد أمان إضافية للوكلاء

استخدم رموز وصول بأقل الامتيازات

احمِ فرع main

راجع كل تغيير قبل الدمج

فوّض التنفيذ واحتفظ بالحكم

سير العمل الكامل

امنح الوكلاء مساحة للعمل دون تسليمهم المفاتيح

أفضل أدوات CLI خفيفة الوزن لتصميم API

ما الذي يجعل أداة CLI خفيفة الوزن؟

Redocly CLI: تدقيق وتجميع مواصفات OpenAPI

Spectral: فرض قواعد أسلوب API ككود

oasdiff: كشف التغييرات الجذرية بين الإصدارات

Optic: التدقيق والمقارنة في أداة واحدة

openapi-generator: توليد SDKs وserver stubs والوثائق

Apidog CLI: تصميم نقاط النهاية والمخططات من الطرفية

كيف تختار الأداة المناسبة؟

سير عمل عملي في CI

الخلاصة

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

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

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

متى تستخدمه؟

الحد العملي

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

مثال في CI

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

تدفق مقترح

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

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

تدفق عملي

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

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

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

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

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

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

كيف تختار؟

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

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

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

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

خاتمة

كيفية إنشاء وثائق API بواسطة وكيل AI مع Apidog CLI

لماذا تستخدم CLI بدلًا من GUI أو خادم MCP؟

إعداد بيئة الوكيل

طقوس الكتابة التي يجب أن يتبعها الوكيل

الخطوة 1: إنشاء المرجع من نقاط النهاية والمخططات

الخطوة 2: كتابة الأدلة، وليس المرجع فقط

الخطوة 3: نشر موقع التوثيق

الخطوة 4: تصدير نسخة محمولة

مثال كامل من البداية إلى النهاية

ربط التدفق بحلقة وكيل أو CI

ملاحظة حول الأذونات

عقبات شائعة

الوكيل أنشأ JSON يدويًا

معرف المشروع مفقود

الخلط بين doc وdocs-site وshared-doc

الرمز المميز غير مضبوط في CI

مرجع $ref يشير إلى مخطط غير موجود

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

ما وكلاء الذكاء الاصطناعي التي يمكنها تشغيل Apidog CLI؟

هل أحتاج إلى خطة مدفوعة؟

هل يمكن للوكيل حذف وثائق موجودة بالخطأ؟

كيف يختلف ذلك عن مولدات توثيق AI؟

خاتمة

أفضل أدوات CLI خفيفة الوزن لمحاكاة API

ما الذي يجعل أداة محاكاة CLI خفيفة الوزن؟

Prism (Stoplight)

2. أنشئ فرع AI من `main`

إنشاء طلب دمج إلى `main` محمي

احمِ فرع `main`

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

الخلط بين `doc` و`docs-site` و`shared-doc`

مرجع `$ref` يشير إلى مخطط غير موجود