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

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

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

لماذا واجهة سطر الأوامر (CLI) وليس الواجهة الرسومية (GUI) أو خادم MCP

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

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

لتحقيق ذلك، تتفوق واجهة سطر الأوامر (CLI) لثلاثة أسباب. إنها حتمية: نفس الأمر ينتج نفس النتيجة. إنها قابلة للبرمجة: يندرج التدفق بأكمله في التكامل المستمر (CI). وتعيد JSON في كل استدعاء، بما في ذلك حقل agentHints.nextSteps الذي يخبر الوكيل بما يمكنه فعله بعد ذلك. هذه النقطة الأخيرة تهم أكثر مما تبدو: فهي تعني أن الوكيل لا يخمن طريقه إلى الأمام، بل يتبع اقتراحات واجهة سطر الأوامر نفسها.

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

قم بتثبيت واجهة سطر الأوامر (CLI) والمصادقة مرة واحدة. يغطي دليل التثبيت الخاص بنا إصدارات Node والمسار؛ ويغطي دليل المصادقة الرموز والأسرار في CI.

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

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

يتم تنفيذ كل عملية كتابة مقابل معرف مشروع (Project ID)، والذي ستجده في إعدادات المشروع (Project Settings) → الإعدادات الأساسية (Basic Settings)، أو عن طريق تشغيل:

apidog project list

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

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

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

# 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 لاختيار الأمر التالي.
- إذا عادت عملية كتابة محظورة بسبب الأذونات، فتوقف واطلب من الإنسان؛ لا تختار حلًا بديلًا.

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

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

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

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

يقوم الوكيل بإنشاء نموذج البيانات القابل لإعادة الاستخدام أولاً، ثم نقطة النهاية التي تشير إليه. يُظهر تشغيل apidog cli-schema get schema-create أن مخطط البيانات يأخذ name وكائن jsonSchema قياسيًا. لذا يكتب الوكيل شيئًا مثل 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 موجودة الآن، وتم عرضها من نفس التعريف الذي يقوم فريقك بتحريره. لا توجد خطوة منفصلة "لتصدير الوثائق" للمرجع؛ فهي مباشرة في المشروع لحظة إطلاق نقطة النهاية. هذا هو المقابل لمصدر يعتمد على المخطط أولاً: لا يمكن للمرجع أن ينحرف، لأنه هو المخطط.

الخطوة 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 للمشروع (ما أنشأته في الخطوة 2).
• 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

نظرًا لأن كل خطوة هي أمر، فإن التدفق بأكمله يندرج في 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) من البداية إلى النهاية، راجع من PRD إلى حلقة الاختبار وكيفية إعداد 5 وكلاء ذكاء اصطناعي لبناء واجهة برمجة تطبيقات كاملة. النمط في كليهما هو نفسه هنا: وصف النية، دع الوكيل يترجمها إلى استدعاءات CLI تم التحقق منها، ثم مراجعة النتيجة.

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

يمكن تقييد الكتابة إلى مشروع من خلال وكيل. إذا عادت عملية create محظورة، فهذا يعني أن المشروع لديه أذونات تحرير AI خارجية معطلة لذلك الفرع. لديك خياران صادقان: تمكين إذن التحرير المباشر في إعدادات المشروع (Project Settings) ← إعدادات الميزات (Feature Settings) ← إعدادات ميزات AI (AI Feature Settings) (عميل 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. إنها ثلاثة أشياء مختلفة: صفحة Markdown في الشجرة، وموقع مستضاف، ورابط مشاركة. اجعل الوكيل يؤكد أي منها تعنيه المهمة قبل أن يكتب.

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

$ref يشير إلى لا شيء. عندما تشير نقطة نهاية إلى نموذج بيانات باستخدام #/definitions/{schemaId}، يجب أن يكون هذا المخطط موجودًا أولاً. أنشئ المخططات قبل نقاط النهاية التي تستخدمها.

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

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

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

هل يمكن للوكيل أن يمحو وثائق موجودة عن طريق الخطأ؟ create يضيف موارد جديدة. تعديل الموارد الموجودة يستخدم update، والذي يتصرف بشكل مختلف ويحتاج إلى حواجز حماية خاصة به؛ وهذا مغطى في الدليل المصاحب لتحديث مواصفات API الخاصة بك.

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

خاتمة

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

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