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) يدويًا عمل دقيق وصعب. إعادة تسمية حقل، أو إضافة قيمة تعداد (enum)، أو جعل حقل مطلوبًا: كل تغيير صغير، لكنه يجب أن يستقر في مكانه الصحيح دون كسر نقاط النهاية (endpoints) التي تعتمد عليه. هذه مهمة مثالية لوكيل ذكاء اصطناعي، بشرط أن يمتلك ضوابط تمنعه من إتلاف المخطط بالكامل.

جرّب Apidog اليوم

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

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

ماذا يعني «تحديث المواصفات» في واجهة سطر الأوامر (CLI)؟

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

  • endpoint update: لتغيير مسار أو معامل أو استجابة.
  • schema update: لتغيير نموذج بيانات تستخدمه نقاط النهاية.
  • import: لاستيراد ملف OpenAPI كامل ومطابقته مع المشروع.

قبل أن تمنح وكيلًا صلاحية تنفيذ أي منها، افهم قاعدتين أساسيتين:

  1. نموذج الأذونات.
  2. سلوك update الذي قد يحذف بيانات بصمت عند استخدامه بشكل خاطئ.

القاعدة الأهم: update هو استبدال كامل وليس Patch

أوامر update في CLI ليست JSON Patch. ترسل الحقول التي تزودها كما هي، ولا تدمج عناصر المصفوفات حسب المعرّف (ID).

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

استخدم دائمًا تسلسل قراءة → تعديل → تحقق → كتابة على الكائن الكامل:

# 1. جلب المورد الحالي بالكامل
apidog endpoint get <endpointId> --project <projectId>

# 2. تعديل البنية الكاملة محليًا مع الاحتفاظ بكل الحقول غير المعدّلة

# 3. التحقق من صحة الكائن الكامل مقابل المخطط
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. إعادة كتابة الكائن الكامل
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

ضع هذه القاعدة صراحة في تعليمات الوكيل:

لا ترسل أبدًا كائنًا جزئيًا إلى update. اجلب المورد كاملًا، وعدّله، ثم أعد إرساله كاملًا.

تخطي خطوة get قد يؤدي إلى حذف حقول بصمت. وتشغيل cli-schema validate قبل الكتابة يكشف الأخطاء قبل وصولها إلى المشروع.

المسار الآمن: اجعل الوكيل يعمل على فرع ذكاء اصطناعي

يمكنك منح الوكيل إذن التحرير المباشر على الفرع الرئيسي، لكن لا تبدأ بهذه الطريقة. استخدم فرع الذكاء الاصطناعي (AI branch) لعزل التغييرات:

  • يعدّل الوكيل الموارد دون لمس الفرع المصدر.
  • لا تُدمج التغييرات تلقائيًا.
  • تراجع الفروقات قبل الموافقة.
  • يمكنك التخلص من الفرع بالكامل إذا أخطأ الوكيل.

فكر فيه كطلب سحب (Pull Request) لمواصفات API.

الخطوة 1: إنشاء فرع الذكاء الاصطناعي 

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

استخدم اصطلاح تسمية واضحًا مثل:

ai/YYYYMMDD-from-source-feature
Enter fullscreen mode Exit fullscreen mode

يجب أن يشير --from إلى فرعك الرئيسي أو فرع سباق (sprint branch) عادي، وليس فرعًا عامًا.

يُؤرشف فرع الذكاء الاصطناعي الذي لا يختلف عن مصدره تلقائيًا بعد 24 ساعة، لذلك لا تتراكم التجارب المهملة.

الخطوة 2: استيراد الموارد التي سيعدلها الوكيل

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

قبل تعديل نقطة نهاية أو مخطط موجود، انقله إلى الفرع باستخدام pick-to:

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 3: نفّذ التعديل على الفرع المعزول

بعد نقل المورد إلى الفرع، شغّل دورة القراءة والتعديل والكتابة مع تحديد --branch:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 4: راجع الفروقات ثم ادمج

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

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

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

يتطلب الدمج المباشر من CLI إذن تحرير مباشر على الفرع المصدر والفرع الهدف. إذا كان main محميًا، استخدم merge-request ثم وافق على الطلب من عميل Apidog.

مثال عملي: إعادة تسمية حقل بأمان

لنفترض أنك تريد إعادة تسمية الحقل amount إلى amountCents في نموذج البيانات Refund، لأن القيمة أصبحت تمثل سنتات كعدد صحيح.

يمكنك إعطاء الوكيل هذه التعليمات:

أعد تسمية الحقل amount في مخطط Refund إلى amountCents واجعله من النوع عدد صحيح.

يجب أن يبدأ الوكيل بجلب المخطط كاملًا من فرع الذكاء الاصطناعي:

# 1. جلب المخطط الكامل الحالي من فرع الذكاء الاصطناعي
apidog schema get <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

ثم يعدّل كائن jsonSchema بالكامل، لا الخاصية المتغيرة فقط:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

لاحظ أن orderId وreason بقيتا كما هما. هذا ضروري لأن update يستبدل الكائن بدل دمجه.

بعد ذلك، تحقّق من صحة الملف ثم اكتب التغيير على فرع الذكاء الاصطناعي:

# 2. التحقق من صحة الكائن الكامل
apidog cli-schema validate schema-create --file ./refund-full.json

# 3. كتابة التحديث على فرع الذكاء الاصطناعي
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

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

أوقف التغييرات المسببة للأعطال قبل الدمج

إعادة تسمية حقل مطلوب هي تغيير مسبب للأعطال (breaking change). أي عميل يرسل amount بدل amountCents سيفشل في التحقق من الصحة.

أضف قاعدة تصنيف صريحة إلى تعليمات الوكيل:

قبل دمج أي تغيير في المواصفات، صنّفه:

- غير مسبب للأعطال:
  حقل اختياري جديد، نقطة نهاية جديدة، أو تخفيف قيد
  → لخّص التغيير وانتقل إلى طلب الدمج.

- مسبب للأعطال:
  حقل تمت إعادة تسميته أو حذفه، حقل مطلوب جديد، أو تضييق نوع/قيد
  → توقّف.
  أبلغ عن التغيير المسبب للأعطال ونقاط النهاية المتأثرة،
  ثم انتظر موافقة بشرية صريحة.
Enter fullscreen mode Exit fullscreen mode

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

التحديث من ملف OpenAPI

أحيانًا يكون التغيير موجودًا بالفعل في ملف OpenAPI تم إنشاؤه من التعليمات البرمجية، أو عدّله فريق آخر، أو يمثل مصدر الحقيقة الخارجي.

بدل إعادة تنفيذ تعديلات حقلًا بحقل، استورد الملف إلى فرع الذكاء الاصطناعي:

apidog import --project <projectId> --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

يقبل import ملفات OpenAPI 3.x وSwagger 2.0 وPostman وغيرها.

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

apidog export --project <projectId> --format openapi \
  --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

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

عندما يخطئ الوكيل: التراجع

إذا أنتج الوكيل تغييرًا غير مرغوب فيه، فلا تدمجه. أرشف الفرع وتابع العمل:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> --type ai
Enter fullscreen mode Exit fullscreen mode

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

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

إذا تم حظر update أو import، فقد يكون المشروع قد عطّل أذونات تحرير الذكاء الاصطناعي الخارجي.

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

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

Project Settings → Feature Settings → AI Feature Settings
Enter fullscreen mode Exit fullscreen mode

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

المشاكل الشائعة

  • التحديث الجزئي يحذف الحقول

    update يستبدل ولا يدمج. اجلب الكائن كاملًا، وعدّله كاملًا، وتحقق من صحته، ثم أرسله.

  • تعديل مورد موجود على فرع AI دون نقله إليه

    يبدأ الفرع فارغًا. استخدم pick-to قبل التعديل.

  • استخدام قيمة خاطئة مع --from

    يجب أن يكون المصدر فرعًا رئيسيًا أو فرع سباق، وليس فرعًا عامًا.

  • تجاوز التحقق من الصحة

    استخدم cli-schema validate قبل أي كتابة. هذا يمنع وصول حمولة غير صحيحة إلى المشروع.

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

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

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

  • هل يمكن للوكيل تعديل الفرع الرئيسي مباشرة؟

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

  • ما الفرق بين branch merge وmerge-request؟

    ينفذ branch merge الدمج مباشرة ويتطلب أذونات تحرير على الفرعين. أما merge-request فيفتح طلبًا قابلًا للمراجعة، وهو الخيار الأفضل للفرع الرئيسي المحمي.

  • هل يحتاج الوكيل إلى تطبيق Apidog لسطح المكتب؟

    لا. CLI مستقل. تحتاج التطبيق فقط لتغيير إعداد أذونات تحرير الذكاء الاصطناعي الخارجي.

  • كيف أتأكد من أن الوكيل لا يخترع أسماء حقول؟

    استخدم تسلسل cli-schema get ثم validate. يجب أن تفشل الحمولة التي تحتوي على حقل غير صالح أثناء التحقق المحلي قبل أن تصل إلى المشروع.

خاتمة

تحديث وكيل ذكاء اصطناعي لمواصفات API يصبح آمنًا عند تطبيق ثلاث قواعد:

  1. العمل على فرع ذكاء اصطناعي معزول.
  2. التعامل مع كل update كعملية قراءة-تعديل-كتابة كاملة.
  3. اشتراط مراجعة بشرية قبل الدمج، خصوصًا للتغييرات المسببة للأعطال.

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

ولإكمال دورة الإنشاء والصيانة، اقرن هذا النهج مع السماح لوكيل بإنشاء وثائق API.

Top comments (0)