لديك نقطة نهاية (endpoint) مُعرفة وترغب في استدعائها من تطبيقك. الجزء الممل هو ترجمة المواصفات إلى شيفرة عاملة: عنوان URL الصحيح، الرؤوس (headers)، رمز المصادقة (auth token)، سلسلة الاستعلام (query string)، كل ذلك يتم ربطه في استدعاء requests أو fetch. انسخ حرفًا واحدًا بشكل خاطئ وتقضي عشرين دقيقة تتساءل لماذا يعيد الخادم رمز 401.
ليس عليك كتابة تلك الشيفرة المتكررة يدويًا. إذا كان واجهة برمجة التطبيقات (API) الخاصة بك مصممة في Apidog، فإن المنصة تقرأ مواصفات نقطة النهاية الخاصة بك وتقدم لك مقتطف طلب جاهز للصق باللغة التي تعمل بها: cURL لإجراء فحص سريع في الطرفية، Python requests لسكريبت، JavaScript fetch أو Axios للواجهة الأمامية. يرشدك هذا الدليل خلال إنشاء تلك الشيفرة من نقطة نهاية حقيقية، ومتى ترسل الطلب أولاً بحيث يحمل المقتطف قيمًا فعلية، وكيف تحافظ على دقة الشيفرة المُنشأة مع تغير مواصفاتك. إذا كنت ترغب في رؤية النطاق الأوسع من الخيارات، فإن ملخصنا لأدوات توليد شيفرة API يمنحك نظرة أوسع؛ هنا سنركز عمليًا على المُولد المدمج.
تعتمد الفكرة على أن المواصفات هي مصدر الحقيقة الوحيد، وهو نفس المبدأ وراء مواصفات OpenAPI. اضبط التعريف بشكل صحيح مرة واحدة، وتتبع شيفرة الطلب من ذلك.
ما يفعله مولد شيفرة العميل بالفعل
يحول Apidog تعريف نقطة نهاية إلى مقتطف طلب لكل نوع لغوي. وجهه إلى GET /orders، اختر Python ومكتبة Requests، وسيقوم بكتابة الاستدعاء الذي يصل إلى ذلك المسار بالرؤوس والمعلمات التي تحددها مواصفاتك. إنه مولد طلبات: ينتج الشيفرة لاستدعاء واحد، في بناء الجملة للغة ومكتبة HTTP التي اخترتها.
اضبط التوقعات بشكل صحيح في نقطة واحدة. هذه الميزة تولد شيفرة الطلب أو شيفرة العميل لنقطة نهاية، وليست حزمة SDK كاملة أو حزمة مكتبة عميل ذات إصدار. إذا كنت بحاجة إلى سطر curl، أو كتلة Python requests، أو مقتطف JS fetch لإسقاطه في شيفرتك، فهذا ما ستحصل عليه. لا تصف الوثائق مولد مكتبة كامل، لذا لا تتوقع حزمة SDK قابلة للتنزيل مع نماذج ومساعدات ترقيم صفحات مدمجة.
يتلاءم هذا بشكل طبيعي مع سير عمل تطوير API بالاعتماد على التصميم أولاً. تحدد العقد، تولد شيفرة الطلب مباشرة منه، وكل مستهلك يبدأ من نفس التعريف الدقيق بدلاً من لقطة شاشة ملصقة في Slack.
طريقتان لفتح المولد
يمنحك Apidog نقطتي دخول لنفس الميزة. استخدم أيهما يتناسب مع مكان تواجدك الحالي.
الأولى من الوثائق. افتح علامة تبويب التوثيق (Documentation tab) لواجهة برمجة التطبيقات الخاصة بك، ثم انقر على زر توليد شيفرة العميل (Generate Client Code) على الجانب الأيمن. هذا هو أسرع مسار عندما تقرأ توثيق نقطة نهاية وتريد استدعاءها.
الثانية من المشغل (runner). في علامة تبويب التشغيل (Run tab) لواجهة برمجة التطبيقات، انقر على أيقونة الشيفرة </>. هذه الأيقونة تقع بجانب المكان الذي تقوم فيه ببناء وإرسال الطلبات، لذا فهي الخيار الطبيعي عندما تختبر الاستدعاء بالفعل.
كلاهما يفتح نفس اللوحة. من هناك تختار لغة ونوعًا، ويقوم Apidog بكتابة المقتطف.
توليد استدعاء عميل Python لـ GET /orders
إليك التدفق الكامل مع نقطة نهاية واقعية: استدعاء GET /orders الذي يسرد طلبات العميل، مصفاة حسب الحالة ومقسمة على صفحات.
الخطوة 1: افتح نقطة النهاية واختر لغتك
افتح علامة تبويب التوثيق (Documentation tab) لنقطة النهاية وانقر على توليد شيفرة العميل (Generate Client Code). في اللوحة، اختر هدفك. يدعم Apidog قائمة طويلة من اللغات والمتغيرات، حتى تتمكن من مطابقة حزمة برامجك تمامًا:
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- أخرى: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R، بالإضافة إلى خيار HTTP خام
لهذا المثال، اختر Python ونوع Requests. يولد Apidog شيئًا كهذا من المواصفات:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
انسخه، أسقطه في سكريبتك، وسيكون استدعاءً عاملاً. هذا هو مسار التصميم أولاً: المقتطف يعكس بالضبط ما تعلنه نقطة النهاية الخاصة بك.
الخطوة 2: اعرف ما يتضمنه المقتطف المعتمد على المواصفات فقط
هناك ملاحظة جديرة بالاهتمام قبل أن تقوم باللصق. الشيفرة التي يتم إنشاؤها مباشرة من مواصفات API تتضمن مواصفات API فقط، وليس قيم معلمات الطلب الحقيقية أو رمز التخويل الخاص بك. تحصل على شكل الاستدعاء وأي قيم أمثلة معرفة في المواصفات، ولكن ليس رأس Authorization: Bearer ... الحي الذي تحتاجه للوصول فعليًا إلى نقطة نهاية محمية.
هذا جيد لاستدعاء بدون مصادقة أو عندما ستقوم بملء الرمز بنفسك. بالنسبة لـ GET /orders المحمي، تريد القيم الحقيقية في الشيفرة.
الخطوة 3: أرسل الطلب أولاً لالتقاط القيم الحقيقية
للحصول على مقتطف يحمل قيم معلمات فعلية ومعلومات التخويل، أرسل الطلب أولاً، ثم اقرأ الشيفرة من علامة التبويب الطلب الفعلي (Actual Request).
إذا كنت تعمل بنظام "التصميم أولاً"، فهذا سهل. حدد نقطة النهاية في علامة تبويب التحرير (Edit tab)، انقر على علامة تبويب التشغيل (Run tab)، وسيتم ملء معلمات الطلب تلقائيًا من المواصفات. إذا كنت تفضل إعداد الأمور يدويًا (وضع "الطلب أولاً")، أدخل معلمات الطلب يدويًا في علامة تبويب التشغيل بدلاً من ذلك. في كلتا الحالتين، أضف رمز التخويل الخاص بك، ثم انقر على إرسال (Send) لإرسال الطلب.
بمجرد عودة الاستجابة، انتقل إلى علامة التبويب الطلب الفعلي (Actual Request) ومرر لأسفل للعثور على شيفرة العميل. الآن يتضمن المقتطف المُنشأ القيم المحددة ورأس التخويل الذي تم إرساله بالفعل:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
هذا هو الفرق بين المسارين. وضع التصميم أولاً يملأ المعلمات تلقائيًا من المواصفات؛ وضع الطلب أولاً يتيح لك كتابتها. كلاهما يغذي نفس مقتطف الطلب الفعلي (Actual Request) بمجرد النقر على إرسال (Send). تعامل مع الرمز الحقيقي مثل الذي أعلاه كسرٍّ واحتفظ به بعيدًا عن أي شيء تقوم بتثبيته في Git؛ نفس العناية التي تحث عليها وثائق Stripe للمفاتيح الحية تنطبق هنا.
التعامل مع أجسام الطلبات لـ POST و PUT
لا يحتوي GET /orders على جسم، ولكن لحظة توليد شيفرة لـ POST /orders أو PUT /orders/{id}، تحتاج إلى جسم طلب في المقتطف. يساعدك Apidog على بناء واحد في علامة تبويب التشغيل (Run tab) قبل التوليد.
بالنسبة لأجسام JSON أو XML، لديك مصدران. استخدم مثالاً محددًا مسبقًا من مواصفات نقطة النهاية، أو انقر على توليد تلقائي (Auto-generate) لإنشاء هيكل جسم يتطابق مع مخططك. القائمة المنسدلة توليد تلقائي (Auto-generate) تمنحك وضعين:
- أمثلة (Examples): اختر يدويًا مثالاً محددًا مسبقًا لجسم الطلب.
- توليد في كل مرة (Generate Each Time): أعد توليد البيانات في كل استخدام، باتباع قواعد وهمية ذكية (smart mock rules) بحيث تحصل على قيم جديدة وصالحة للمخطط في كل مرة.
يمكنك توجيه كيفية إنتاج البيانات من خلال الخيارات الفرعية تفضيلات التوليد التلقائي (Auto-generation Preference): استخدام قيم الأمثلة أولاً (Use Example Values First)، استخدام القيم الافتراضية أولاً (Use Default Values First)، استخدام قيمة وهمية (Use Mock Value)، توليد أسماء الحقول فقط (Generate Field Names Only)، و استخدام مثال الطلب (Use Request Example). اختر استخدام قيم الأمثلة أولاً (Use Example Values First) عندما تحتوي مواصفاتك على أمثلة جيدة وتريد احترامها؛ اختر استخدام قيمة وهمية (Use Mock Value) عندما تريد بيانات واقعية مُولدة لكل حقل.
ملاحظة عن الإصدار: تتطلب خيارات التوليد التلقائي (Auto-generate) لأجسام الطلبات Apidog 2.7.0 أو أحدث. إذا لم ترها، قم بتحديث التطبيق. مخطط محدد جيدًا مع أمثلة، النوع الذي تحصل عليه من توليد وثائق API تلقائيًا من OpenAPI، يجعل هذه الخطوة تنتج أجسامًا نظيفة مع القليل جدًا من التعديل اليدوي.
عندما تحتاج إلى قيمة تتغير لكل طلب، مثل طابع زمني جديد أو معرف طلب عشوائي، أدخل قيمة ديناميكية بدلاً من ترميزها الثابت. انقر على أيقونة العصا السحرية (magic wand) بجانب مربع إدخال المعلمة، أو استخدم زر إدراج قيمة ديناميكية (Insert Dynamic Value) داخل جسم طلب JSON أو XML. بعد أن يصبح الجسم جاهزًا، انقر على إرسال (Send)، ثم اقرأ المقتطف النهائي من علامة التبويب الطلب الفعلي (Actual Request) كما كان من قبل.
متى تستخدم مقتطف طلب مقابل استدعاء نموذج أعمال
حكم سريع: كم من الشيفرة يجب أن تنسخها؟
استخدم مقتطف طلب واحد (cURL، fetch، requests.get مجرد) عندما تقوم بعمل لمرة واحدة. تصحيح الأخطاء لماذا تعيد نقطة نهاية 403، مشاركة استدعاء قابل للتكرار في تذكرة، إجراء فحص سريع في الطرفية، أو لصق مثال في وثائقك الخاصة. إنه مستقل ولا يحتاج إلى بنية محيطة.
امِل نحو شيفرة نمط نموذج الأعمال الأكثر اكتمالاً (كتلة Axios أو requests مع الرؤوس، المعلمات، والتعامل مع الاستجابة) عندما يعيش الاستدعاء داخل منطق تطبيق حقيقي. إذا كان GET /orders سيجلس في وحدة خدمة يتم استدعاؤها من ثلاثة أماكن، فأنت تريد النسخة المنظمة التي يمكنك تضمينها في دالة، وإضافة معالجة الأخطاء إليها، وإعادة استخدامها. يوفر لك المولد كلا الشكلين اعتمادًا على النوع الذي تختاره؛ طابق الشكل مع المكان الذي ستعيش فيه الشيفرة.
إذا كنت تستدعي نفس نقاط النهاية بنفس المصادقة عبر مشروع كامل، فغالبًا ما يكون من الأفضل مركزة الأجزاء المشتركة. يوضح دليلنا حول تعيين المعلمات العامة في Apidog كيفية تحديد الرؤوس والمتغيرات مرة واحدة بحيث ترثها كل مكالمة مُنشأة بدلاً من تكرار الرمز في كل مقتطف.
الحفاظ على دقة الشيفرة المُنشأة من خلال عادة "المواصفات أولاً"
الشيفرة المُنشأة تكون صحيحة فقط بقدر صحة المواصفات التي تقف خلفها. غيّر GET /orders لإضافة معلمة استعلام region ونسيت إعادة التوليد، وسيصبح المقتطف المنسوخ خاطئًا بصمت. الحل هو التعامل مع المواصفات على أنها الشيء الذي تحتفظ به، والشيفرة كناتج مشتق تقوم بإعادة توليده عند الطلب. يحافظ وضع "المواصفات أولاً" في Apidog على سلطة التعريف بحيث تعكس شيفرة الطلب التي تولدها دائمًا العقد الحالي، وليس عقدًا قديمًا.
بالنسبة لبناء جملة المقتطفات نفسها، فإن وثائق MDN حول Fetch API هي مرجع قوي عندما تريد فهم أو تعديل أنواع JavaScript التي ينتجها Apidog.
أتمتة سير العمل باستخدام واجهة سطر الأوامر (CLI) في Apidog
توليد الشيفرة نفسه هو إجراء رسومي؛ تنسخ مقتطفًا من لوحة، ولا يوجد أمر سطر أوامر منفصل يصدر شيفرة العميل. ما يفعله Apidog CLI بشكل جيد هو الحفاظ على الشيئين اللذين يعتمد عليهما التوليد: مواصفات حديثة واختبارات ناجحة تثبت أن العميل المُنشأ يعمل بالفعل.
قم بتثبيته باستخدام npm install -g apidog-cli (Node.js v16+) والمصادقة:
apidog login --with-token <رمز_الوصول_الخاص_بك>
استورد تغييرات المواصفات الجديدة لكي تظل الشيفرة التي تولدها حديثة، وشغل سيناريو الاختبار المحفوظ الذي يمارس نقطة النهاية التي يستدعيها عميلك:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <معرف_السيناريو> -e <معرف_البيئة> -r cli
هنا -t هو معرف سيناريو الاختبار، -e هو معرف البيئة، و -r هو المُبلغ (cli، html، أو junit). اربط هذا في خط أنابيبك، بالطريقة التي يوضحها دليل Apidog CLI GitHub Actions، وكل عملية دفع تتحقق من أن GET /orders لا يزال يتصرف كما تعد به المواصفات قبل أن يقوم أي شخص بإعادة توليد عميل منه. لا يكتب CLI شيفرة عميلك، ولكنه يحمي العقد الذي بُنيت عليه تلك الشيفرة.
الأسئلة الشائعة
هل تتضمن الشيفرة المُنشأة مفتاح API والرمز الخاص بي؟
ليس افتراضيًا. الشيفرة التي تم إنشاؤها من مواصفات API وحدها تتضمن المواصفات فقط، وليس قيم المعلمات الحقيقية أو التخويل. للحصول على مقتطف يحتوي على الرمز والقيم الفعلية الخاصة بك، أرسل الطلب أولاً، ثم اقرأ الشيفرة من علامة التبويب الطلب الفعلي (Actual Request). تعامل مع أي رمز في هذا المقتطف كسر.
ما هي اللغات والمكتبات التي يمكن لـ Apidog توليد شيفرة لها؟
مجموعة واسعة. Shell (cURL، Httpie، wget، PowerShell)، JavaScript (Fetch، Axios، jQuery، XHR، والمزيد)، Python (http.client و Requests)، Java (Unirest، OkHttp)، Go، PHP، Swift، C، C#، Ruby، Dart، R، وغيرها. تختار اللغة والمتغير المحدد في لوحة المولد.
لماذا لا أرى خيارات التوليد التلقائي لأجسام الطلبات؟
تتطلب هذه الخيارات Apidog 2.7.0 أو أحدث. قم بتحديث التطبيق وستظهر في علامة تبويب التشغيل (Run tab) عند بناء جسم JSON أو XML. بمجرد توفرها، تقدم القائمة المنسدلة توليد تلقائي (Auto-generate) خياري أمثلة (Examples) و توليد في كل مرة (Generate Each Time)، مع خيارات فرعية للتفضيلات حول كيفية إنتاج القيم.
هل توليد شيفرة العميل ميزة مدفوعة؟
لا تحدد وثائق Apidog خطًا فاصلاً بين المجاني والمدفوع أو السحابي والمستضاف ذاتيًا لتوليد شيفرة العميل. الشرط الوحيد للإصدار المذكور هو أن خيارات التوليد التلقائي (Auto-generate) لأجسام الطلبات تحتاج إلى الإصدار 2.7.0 أو أحدث. يمكنك تنزيل Apidog وتجربة المولد بدون خطة مدفوعة.
كيف أتأكد من أن الاستدعاء المُنشأ يعمل بالفعل؟
قم بتوليد المقتطف، ثم تحقق من نقطة النهاية باستخدام اختبار محفوظ. يوضح دليلنا حول كتابة سيناريو اختبار باستخدام Apidog كيفية بناء واحد، ويمكن لـ CLI تشغيله في التكامل المستمر (CI) بحيث يؤدي العقد المكسور إلى فشل البناء قبل إعادة توليد عميل منه.
الخلاصة
يحوّل توليد شيفرة العميل في Apidog مواصفات نقطة نهاية إلى طلب جاهز للصق بأي لغة تعمل بها، وتعد علامة التبويب الطلب الفعلي (Actual Request) هي الحيلة للحصول على قيم حقيقية ومصادقة في ذلك المقتطف بدلاً من قالب فارغ. حافظ على سلطة المواصفات، وأعد التوليد عند التغيير، ودع اختبارًا محفوظًا يؤكد أن الاستدعاء لا يزال يعمل. قم بتنزيل Apidog للمتابعة، حدد نقطة النهاية GET /orders الخاصة بك، وانسخ استدعاء عميل عامل بنقرتين.