DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

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

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

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

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

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

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

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

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

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

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

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

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

واجهة Apidog CLI

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

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

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

إعدادات رمز الوصول إلى API

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

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

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

apidog project list
Enter fullscreen mode Exit fullscreen mode

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

تشغيل Apidog CLI مع وكيل

نتائج أوامر Apidog CLI

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

أوامر التوثيق التي تنشئ موارد تتطلب ملف 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
Enter fullscreen mode Exit fullscreen mode

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

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

هذه الحلقة:

cli-schema get → cli-schema validate → create
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

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

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

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

أنشئ ملف 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" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

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

#/definitions/{schemaId}
Enter fullscreen mode Exit fullscreen mode

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

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

ثم نفّذ:

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

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

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

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

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

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

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

أنشئ ملف quickstart.json:

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

ثم نفّذ:

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

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

اكتب دليل بدء سريع يشرح للمطور الجديد الانتقال من مفتاح 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
Enter fullscreen mode Exit fullscreen mode

استخدم 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
Enter fullscreen mode Exit fullscreen mode

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

apidog export --help
Enter fullscreen mode Exit fullscreen mode

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

--scope
--api-ids
--folder-ids
Enter fullscreen mode Exit fullscreen mode

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

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

لقد أضفنا للتو خدمة مدفوعات تتضمن 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
Enter fullscreen mode Exit fullscreen mode

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

ربط التدفق بحلقة وكيل أو 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
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

لديك خياران:

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

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

عقبات شائعة

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

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

cli-schema get → cli-schema validate → create
Enter fullscreen mode Exit fullscreen mode

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

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

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

--project <projectId>
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

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

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

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

apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

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

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

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

#/definitions/{schemaId}
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

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

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

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

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

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

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

خاتمة

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

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

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

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

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

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

Top comments (0)