DEV Community

Cover image for كيفية توليد كود العميل من مواصفات API الخاصة بك في Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية توليد كود العميل من مواصفات API الخاصة بك في Apidog

لديك نقطة نهاية (endpoint) مُعرّفة وتريد استدعاءها من تطبيقك. الجزء الممل هو تحويل المواصفات إلى شيفرة تعمل: عنوان URL الصحيح، الرؤوس (headers)، رمز المصادقة (auth token)، ومعلمات الاستعلام (query string). خطأ حرف واحد قد يتركك تبحث عن سبب استجابة الخادم بالرمز 401.

جرّب Apidog اليوم

بدل كتابة هذه الشيفرة المتكررة يدويًا، يمكن لـ Apidog قراءة مواصفات نقطة النهاية وتوليد مقتطف طلب جاهز للصق باللغة والمكتبة التي تستخدمها: cURL للاختبار السريع في الطرفية، وPython requests للسكريبتات، وJavaScript fetch أو Axios للواجهة الأمامية. يشرح هذا الدليل كيفية توليد المقتطف من نقطة نهاية فعلية، وكيف تحصل على قيم المصادقة والمعلمات الحقيقية، وكيف تُبقي الشيفرة متزامنة مع تغيّر المواصفات. وللاطلاع على خيارات أوسع، راجع دليل أدوات توليد شيفرة API.

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

ما الذي يولّده مولد شيفرة العميل؟

يحوّل Apidog تعريف نقطة النهاية إلى مقتطف طلب للغة والمكتبة التي تختارها. إذا كانت لديك نقطة نهاية مثل:

GET /orders
Enter fullscreen mode Exit fullscreen mode

واخترت Python مع مكتبة Requests، فسيولّد Apidog استدعاءً يحتوي على المسار والرؤوس والمعلمات المعرفة في مواصفاتك.

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

  • أمر cURL لتشخيص سريع.
  • مقتطف requests في Python.
  • استدعاء fetch أو Axios في JavaScript.
  • مثال قابل للنسخ إلى وثائقك أو تذكرة خطأ.

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

طريقتان لفتح مولد الشيفرة

يوفر Apidog نقطتي دخول للمولد نفسه.

من علامة تبويب التوثيق

  1. افتح علامة تبويب التوثيق (Documentation tab).
  2. انتقل إلى نقطة النهاية المطلوبة.
  3. انقر توليد شيفرة العميل (Generate Client Code) على الجانب الأيمن.
  4. اختر اللغة والمكتبة.
  5. انسخ المقتطف.

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

من علامة تبويب التشغيل

  1. افتح نقطة النهاية في علامة تبويب التشغيل (Run tab).
  2. اضبط المعلمات والرؤوس والجسم عند الحاجة.
  3. انقر أيقونة الشيفرة </>.
  4. اختر اللغة والمكتبة.
  5. انسخ الشيفرة الناتجة.

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

توليد استدعاء Python لـ GET /orders

لنستخدم نقطة نهاية واقعية:

GET /orders
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 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. قد ينتج المولد مقتطفًا مثل التالي:

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())
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 2: افهم ما تتضمنه الشيفرة المولّدة من المواصفات

المقتطف الذي يولّد مباشرة من مواصفات API يتضمن ما هو موجود في المواصفات:

  • عنوان URL والمسار.
  • الرؤوس المعرفة.
  • المعلمات وقيم الأمثلة.
  • شكل جسم الطلب عند توفره.

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

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>"
}
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 3: أرسل الطلب للحصول على القيم الحقيقية

لإنشاء مقتطف يحتوي على المعلمات المحددة ومعلومات التخويل المستخدمة فعليًا:

  1. افتح نقطة النهاية في علامة تبويب التشغيل (Run tab).
  2. أضف معلمات الطلب، مثل status=shipped وpage=1.
  3. أضف رمز التخويل في الرأس المناسب.
  4. انقر إرسال (Send).
  5. بعد وصول الاستجابة، افتح علامة تبويب الطلب الفعلي (Actual Request).
  6. مرّر إلى قسم شيفرة العميل، ثم انسخ اللغة والمكتبة المطلوبتين.

سيكون المقتطف الناتج أقرب إلى هذا المثال:

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())
Enter fullscreen mode Exit fullscreen mode

في وضع التصميم أولًا، يملأ Apidog المعلمات من المواصفات. وفي وضع الطلب أولًا، تدخلها يدويًا في علامة تبويب التشغيل. في الحالتين، تصبح شيفرة الطلب الفعلي (Actual Request) متاحة بعد إرسال الطلب.

تعامل مع أي رمز حقيقي يظهر في المقتطف كسر. لا تثبّت الرموز في Git ولا تشاركها في تذاكر عامة. تنطبق هنا نفس ممارسات التعامل مع المفاتيح الحية التي توصي بها وثائق Stripe.

التعامل مع أجسام الطلب في POST وPUT

لا يحتوي GET /orders على جسم طلب، لكن نقاط نهاية مثل:

POST /orders
PUT /orders/{id}
Enter fullscreen mode Exit fullscreen mode

تحتاج إلى جسم JSON أو XML. جهّز الجسم في علامة تبويب التشغيل (Run tab) قبل توليد الشيفرة.

لإنشاء جسم الطلب:

  1. افتح نقطة النهاية في علامة تبويب التشغيل.
  2. اختر نوع المحتوى المناسب، مثل JSON أو XML.
  3. استخدم مثالًا معرّفًا في المواصفات، أو انقر توليد تلقائي (Auto-generate).
  4. راجع القيم الناتجة وعدّل الحقول المطلوبة.
  5. أرسل الطلب.
  6. انسخ الشيفرة من علامة تبويب الطلب الفعلي (Actual Request).

تتضمن قائمة توليد تلقائي (Auto-generate) وضعين:

  • أمثلة (Examples): اختيار مثال طلب محدد مسبقًا.
  • توليد في كل مرة (Generate Each Time): إعادة إنشاء بيانات جديدة في كل استخدام وفق قواعد بيانات وهمية ذكية.

يمكنك أيضًا تحديد تفضيلات التوليد التلقائي (Auto-generation Preference):

  • استخدام قيم الأمثلة أولًا (Use Example Values First).
  • استخدام القيم الافتراضية أولًا (Use Default Values First).
  • استخدام قيمة وهمية (Use Mock Value).
  • توليد أسماء الحقول فقط (Generate Field Names Only).
  • استخدام مثال الطلب (Use Request Example).

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

تتطلب خيارات التوليد التلقائي (Auto-generate) لأجسام الطلبات Apidog 2.7.0 أو أحدث. إذا لم تظهر الخيارات، حدّث التطبيق.

كلما كان المخطط محددًا بوضوح ويحتوي أمثلة جيدة، كانت الأجسام المولّدة أدق. راجع أيضًا دليل توليد وثائق API تلقائيًا من OpenAPI لتحسين جودة المواصفات والأمثلة.

إذا احتجت قيمة مختلفة في كل طلب، مثل طابع زمني أو معرّف عشوائي:

  1. انقر أيقونة العصا السحرية (magic wand) بجانب حقل المعلمة.
  2. أو استخدم إدراج قيمة ديناميكية (Insert Dynamic Value) داخل جسم JSON أو XML.
  3. أرسل الطلب.
  4. انسخ المقتطف النهائي من الطلب الفعلي (Actual Request).

متى تستخدم مقتطف طلب، ومتى تستخدم استدعاءً منظمًا؟

استخدم مقتطف طلب بسيطًا، مثل cURL أو fetch أو requests.get، في الحالات التالية:

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

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

import os
import requests

API_URL = "https://api.example.com"
API_TOKEN = os.environ["API_TOKEN"]

def get_orders(status: str, page: int = 1):
    response = requests.get(
        f"{API_URL}/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        params={
            "status": status,
            "page": page,
        },
        timeout=30,
    )

    response.raise_for_status()
    return response.json()
Enter fullscreen mode Exit fullscreen mode

المولد يوفر نقطة بداية، ثم يمكنك إضافة:

  • معالجة الأخطاء.
  • المهلات الزمنية.
  • التسجيل (logging).
  • إعادة المحاولة.
  • إدارة الرموز عبر متغيرات البيئة.

إذا كانت عدة نقاط نهاية تشترك في نفس الرؤوس أو المتغيرات، فركّز الإعدادات المشتركة بدل تكرارها. يشرح دليل تعيين المعلمات العامة في Apidog كيفية تعريف الرؤوس والمتغيرات مرة واحدة لكي ترثها الطلبات.

الحفاظ على دقة الشيفرة عبر عادة «المواصفات أولًا»

الشيفرة المولّدة صحيحة بقدر صحة المواصفات التي تعتمد عليها. إذا أضفت مثلًا معلمة region إلى:

GET /orders
Enter fullscreen mode Exit fullscreen mode

لكن استمررت في استخدام مقتطف قديم، فلن يحتوي على المعلمة الجديدة.

اتبع هذا التسلسل عند تغيير العقد:

  1. حدّث مواصفات نقطة النهاية.
  2. راجع المعلمات والرؤوس والأمثلة.
  3. أرسل طلب اختبار من علامة تبويب التشغيل.
  4. ولّد مقتطفًا جديدًا أو انسخه من الطلب الفعلي.
  5. حدّث شيفرة التطبيق عند الحاجة.
  6. شغّل اختبارًا محفوظًا للتحقق من استمرار عمل العقد.

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

ولفهم مقتطفات JavaScript أو تعديلها، استخدم وثائق MDN حول Fetch API كمرجع لبناء الجملة وسلوك الاستدعاءات.

أتمتة التحقق باستخدام Apidog CLI

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

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

ثبّت CLI باستخدام Node.js v16 أو أحدث:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

ثم سجّل الدخول باستخدام رمز الوصول:

apidog login --with-token <رمز_الوصول_الخاص_بك>
Enter fullscreen mode Exit fullscreen mode

شغّل سيناريو اختبار محفوظًا لنقطة النهاية:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <معرف_السيناريو> -e <معرف_البيئة> -r cli
Enter fullscreen mode Exit fullscreen mode

حيث:

  • -t: معرّف سيناريو الاختبار.
  • -e: معرّف البيئة.
  • -r: نوع المُبلّغ، مثل cli أو html أو junit.

أضف هذا الأمر إلى خط أنابيب التكامل المستمر. يوضح دليل Apidog CLI GitHub Actions طريقة ربط الاختبارات بـ GitHub Actions.

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

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

هل تتضمن الشيفرة المولّدة مفتاح 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 وغيرها.

اختر اللغة والمكتبة من لوحة المولد.

لماذا لا تظهر خيارات التوليد التلقائي لجسم الطلب؟

تتطلب خيارات التوليد التلقائي (Auto-generate) الإصدار 2.7.0 أو أحدث من Apidog. بعد التحديث، ستظهر في علامة تبويب التشغيل (Run tab) عند إعداد جسم JSON أو XML.

هل توليد شيفرة العميل ميزة مدفوعة؟

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

يمكنك تنزيل Apidog وتجربة المولد دون خطة مدفوعة.

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

ولّد المقتطف، ثم اختبر نقطة النهاية باستخدام سيناريو محفوظ. يشرح دليل كتابة سيناريو اختبار باستخدام Apidog كيفية إعداد السيناريو، ويمكن لـ CLI تشغيله في CI لمنع اعتماد عقد مكسور.

الخلاصة

يحوّل توليد شيفرة العميل في Apidog مواصفات نقطة النهاية إلى طلب جاهز للصق باللغة والمكتبة التي تستخدمها. للحصول على معلمات ومصادقة حقيقية بدل قالب عام، أرسل الطلب أولًا ثم انسخ المقتطف من علامة تبويب الطلب الفعلي (Actual Request).

حافظ على المواصفات كمصدر الحقيقة، وأعد توليد المقتطفات عند تغيير العقد، واربط اختباراتك المحفوظة بـ CI للتحقق من استمرار عمل نقطة النهاية. نزّل Apidog، افتح نقطة النهاية GET /orders، وولّد استدعاء عميل قابلًا للتنفيذ خلال دقائق.

Top comments (0)