كيفية إضافة أمثلة متعددة لجسم الطلب في Apidog

@apidog

@apidog

17 يونيو 2025

كيفية إضافة أمثلة متعددة لجسم الطلب في Apidog

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

أمثلة جسم الطلب مفيدة لأنها:

يمكنك إضافة العديد منها حسب الحاجة لتغطية جميع السيناريوهات الممكنة.

الخطوة بخطوة: إضافة أول مثال لجسم الطلب الخاص بك

إضافة أمثلة لجسم الطلب في Apidog بسيطة. إليك كيفية البدء:

1. افتح مشروع API الخاص بك في Apidog (الإصدار 2.7.0 أو أعلى)

2. انتقل إلى نقطة النهاية حيث تريد إضافة الأمثلة

3. انقر على علامة "تعديل" للوصول إلى محرر الوثائق وقم بالتمرير إلى قسم "جسم الطلب"

4. انقر على "إضافة مثال" لإنشاء مثال جديد

5. املأ تفاصيل المثال:

تكوين مثال جسم الطلب

6. انقر على "حفظ" لإنشاء المثال

يساعد اسم المثال المستخدمين على تحديد غرض كل مثال. إذا تركت الحقل فارغًا، سيقوم Apidog تلقائيًا بتسميته "مثال 1" و"مثال 2" وهكذا.

يجب أن تُظهر قيمة المثال هيكل طلب صالح. بالنسبة لأنواع المحتوى JSON، يوفر Apidog محررًا منظمًا للمساعدة في ضمان التنسيق الصحيح.

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

مفتاح OAS مهم إذا كنت تخطط لتصدير وثائقك إلى تنسيق OpenAPI. يصبح هذا المفتاح هو المعرف للمثال في المواصفة المصدرة.

إنشاء أمثلة متعددة لسيناريوهات مختلفة

بعد إضافة أول مثال لك، سترغب في إنشاء أمثلة إضافية لحالات استخدام مختلفة:

  1. انقر على زر "+ إضافة" مرة أخرى لإنشاء مثال آخر
  2. أعطه اسمًا مميزًا يحدد السيناريو بوضوح (مثل "طلب الحد الأدنى")
  3. أدخل قيمة المثال لهذا السيناريو المحدد
  4. أضف وصفًا تفصيليًا يشرح متى يجب استخدام هذا المثال
  5. قم بتكوين مفتاح OAS والامتدادات حسب الحاجة
  6. انقر على "حفظ" لإضافة المثال
  7. كرر هذه العملية لجميع السيناريوهات ذات الصلة
إضافة مثال آخر لجسم الطلب في وثائق نقطة النهاية

عند إنشاء أمثلة متعددة، ضع في اعتبارك تغطية هذه السيناريوهات الشائعة:

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

يعرض Apidog الأمثلة بترتيب محدد:

توثيق أمثلة جسم الطلب باستخدام Apidog

لجعل أمثلتك الأهم تظهر أولاً، امنحها أسماء واضحة ومفاتيح OAS.

استخدام أمثلة جسم الطلب للاختبار

إحدى أفضل ميزات أمثلة جسم الطلب المتعددة هي كيفية تسهيلها للاختبار:

  1. انتقل إلى صفحة "التشغيل" لنقطة النهاية الخاصة بك
  2. ابحث عن قسم "توليد تلقائي" في تكوين الطلب
  3. انقر على القائمة المنسدلة لرؤية جميع الأمثلة المتاحة
  4. اختر المثال الذي ترغب في اختباره
  5. سيتم ملء جسم الطلب تلقائيًا بالمثال المحدد
  6. انقر على "إرسال" لاختبار نقطة النهاية بهذا المثال
استخدام أمثلة جسم الطلب للاختبار

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

يتيح لك Apidog أيضًا إنشاء أمثلة من جلسات الاختبار الخاصة بك:

  1. قم بتكوين جسم الطلب في صفحة "التشغيل"
  2. انقر على زر "استخراج"
  3. اختر "استخراج إلى مثال الطلب"
  4. اختر إنشاء مثال جديد أو تحديث مثال موجود
  5. سيتم حفظ جسم الطلب الحالي الخاص بك كمثال
استخراج جسم الطلب كمثال

هذا مفيد عندما تجد هيكل طلب يعمل أثناء الاختبار وتريد حفظه للرجوع إليه لاحقًا أو للتوثيق.

ضمان توافق OpenAPI مع أمثلتك

تم تصميم أمثلة جسم الطلب في Apidog للعمل بسلاسة مع مواصفات OpenAPI. عند تصدير وثائق API الخاصة بك، يتم تنسيق جميع أمثلتك بشكل صحيح وفقًا لمعايير OAS 3.0/3.1.

إليك كيفية التعامل مع الأمثلة أثناء التصدير:

  1. تُدرج كل مثال في المواصفة المصدرة
  2. تأتي أسماء الأمثلة من مفتاح OAS إذا تم تقديمه (أو الأرقام التسلسلية إذا لم يتم ذلك)
  3. تُحفظ أوصاف الأمثلة في التنسيق المصدّر
  4. تُدرج أي امتدادات OAS مخصصة في التصدير

ستحتوي المواصفة المصدرّة لمواصفات OpenAPI على أمثلتك في هيكل مثل هذا:

"examples": {
  "standard_request": {
    "value": {
      "name": "جون دو",
      "id": "12345",
      "email": "john.doe@example.com"
    },
    "summary": "طلب قياسي",
    "description": "هذا طلب قياسي مع جميع الحقول المطلوبة."
  },
  "minimal_request": {
    "value": {
      "id": "12345"
    },
    "summary": "طلب الحد الأدنى",
    "description": "هذا طلب الحد الأدنى مع حقل ID المطلوب فقط."
  }
}

لضمان أفضل توافق مع OpenAPI:

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

أفضل الممارسات لأمثلة جسم الطلب

لتحقيق أقصى قيمة من أمثلة جسم الطلب المتعددة، اتبع هذه الممارسات الجيدة:

إنشاء مجموعات شاملة من الأمثلة

تضمن أمثلة تغطي:

استخدم أسماء واضحة

اكتب أوصافًا مفيدة

تنظيم الأمثلة بشكل منطقي

استخدم مفاتيح OAS بشكل فعال

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

الخاتمة

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

العملية خطوة بخطوة بسيطة:

  1. انتقل إلى نقطة النهاية الخاصة بك وانقر على "تعديل"
  2. قم بالتمرير إلى قسم جسم الطلب وانقر على "+ إضافة"
  3. قم بتكوين مثالك باسم، قيمة، وصف، ومفتاح OAS
  4. كرر ذلك من أجل السيناريوهات الإضافية
  5. استخدم أمثلتك للاختبار والتوثيق

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

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

زر

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات