يدعم Apidog إضافة عدة أمثلة لجسم الطلب لكل نقطة نهاية، مما يجعل وثائق API أكثر فائدة وتوافقاً مع مواصفات OpenAPI. تتيح لك هذه الميزة عرض طرق مختلفة لبناء الطلبات لنفس نقطة النهاية، مما يساعد المطورين على فهم كيفية استخدام API في حالات مختلفة.
أمثلة جسم الطلب مفيدة لأنها:
- تظهر للمطورين بالضبط كيفية تنسيق طلباتهم
- توضح حالات استخدام مختلفة لنفس نقطة النهاية
- تسهل الاختبار من خلال تقديم هياكل طلبات جاهزة للاستخدام
- تضمن أن توثيقك يتوافق مع معايير OpenAPI
يمكنك إضافة العديد منها حسب الحاجة لتغطية جميع السيناريوهات الممكنة.
الخطوة بخطوة: إضافة أول مثال لجسم الطلب الخاص بك
إضافة أمثلة لجسم الطلب في Apidog بسيطة. إليك كيفية البدء:
1. افتح مشروع API الخاص بك في Apidog (الإصدار 2.7.0 أو أعلى)
2. انتقل إلى نقطة النهاية حيث تريد إضافة الأمثلة
3. انقر على علامة "تعديل" للوصول إلى محرر الوثائق وقم بالتمرير إلى قسم "جسم الطلب"
4. انقر على "إضافة مثال" لإنشاء مثال جديد

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

- اسم المثال: أعطِ مثالَك اسمًا واضحًا (مثل "طلب قياسي")
- قيمة المثال: أدخل البيانات الفعلية بصيغة JSON أو XML أو أي تنسيق آخر
- الوصف: شرح متى يجب استخدام هذا المثال (يدعم Markdown)
- مفتاح OAS: قدم معرفًا لتصدير OpenAPI (اختياري ولكن يُنصح به)
- امتدادات OAS: أضف أي حقول مخصصة تحتاجها للتصدير (اختياري)
6. انقر على "حفظ" لإنشاء المثال
يساعد اسم المثال المستخدمين على تحديد غرض كل مثال. إذا تركت الحقل فارغًا، سيقوم Apidog تلقائيًا بتسميته "مثال 1" و"مثال 2" وهكذا.
يجب أن تُظهر قيمة المثال هيكل طلب صالح. بالنسبة لأنواع المحتوى JSON، يوفر Apidog محررًا منظمًا للمساعدة في ضمان التنسيق الصحيح.
حقل الوصف هو المكان الذي يمكنك فيه شرح متى ولماذا قد يستخدم شخص ما هذا الهيكل المحدد من الطلب. استخدام Markdown هنا يمكن أن يجعل تفسيراتك أكثر وضوحًا.
مفتاح OAS مهم إذا كنت تخطط لتصدير وثائقك إلى تنسيق OpenAPI. يصبح هذا المفتاح هو المعرف للمثال في المواصفة المصدرة.
إنشاء أمثلة متعددة لسيناريوهات مختلفة
بعد إضافة أول مثال لك، سترغب في إنشاء أمثلة إضافية لحالات استخدام مختلفة:
- انقر على زر "+ إضافة" مرة أخرى لإنشاء مثال آخر
- أعطه اسمًا مميزًا يحدد السيناريو بوضوح (مثل "طلب الحد الأدنى")
- أدخل قيمة المثال لهذا السيناريو المحدد
- أضف وصفًا تفصيليًا يشرح متى يجب استخدام هذا المثال
- قم بتكوين مفتاح OAS والامتدادات حسب الحاجة
- انقر على "حفظ" لإضافة المثال
- كرر هذه العملية لجميع السيناريوهات ذات الصلة

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

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

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

هذا مفيد عندما تجد هيكل طلب يعمل أثناء الاختبار وتريد حفظه للرجوع إليه لاحقًا أو للتوثيق.
ضمان توافق OpenAPI مع أمثلتك
تم تصميم أمثلة جسم الطلب في Apidog للعمل بسلاسة مع مواصفات OpenAPI. عند تصدير وثائق API الخاصة بك، يتم تنسيق جميع أمثلتك بشكل صحيح وفقًا لمعايير OAS 3.0/3.1.
إليك كيفية التعامل مع الأمثلة أثناء التصدير:
- تُدرج كل مثال في المواصفة المصدرة
- تأتي أسماء الأمثلة من مفتاح OAS إذا تم تقديمه (أو الأرقام التسلسلية إذا لم يتم ذلك)
- تُحفظ أوصاف الأمثلة في التنسيق المصدّر
- تُدرج أي امتدادات 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:
- استخدم مفاتيح OAS ذات معنى لجميع الأمثلة
- قدم أوصافًا واضحة تشرح غرض كل مثال
- راجع مواصفاتك المصدرّة للتحقق من أن كل شيء يبدو صحيحًا
هذا يضمن أن تبقى أمثلتك قيمة ليس فقط داخل Apidog ولكن أيضًا عند مشاركتها من خلال مواصفات OpenAPI.
أفضل الممارسات لأمثلة جسم الطلب
لتحقيق أقصى قيمة من أمثلة جسم الطلب المتعددة، اتبع هذه الممارسات الجيدة:
إنشاء مجموعات شاملة من الأمثلة
تضمن أمثلة تغطي:
- الاستخدام الأساسي مع الحقول المطلوبة فقط
- الاستخدام النموذجي مع الحقول الاختيارية الشائعة الاستخدام
- الاستخدام الكامل الذي يعرض جميع الحقول الممكنة
- حالات الحد الأقصى التي تعرض المواقف الخاصة
استخدم أسماء واضحة
- اعطِ كل مثال اسمًا وصفيًا يشير إلى غرضه
- استخدم أنماط تسمية متسقة عبر نقاط النهاية المختلفة
- تجنب الأسماء العامة مثل "مثال 1" التي لا تفسر المحتوى
اكتب أوصافًا مفيدة
- اشرح متى ولماذا قد يستخدم شخص ما كل مثال
- اذكر أي اعتبارات خاصة لهذا الهيكل من الطلب
- استخدم تنسيق Markdown لجعل الأوصاف أسهل قراءة
- تضمين الاستجابات المتوقعة عند الاقتضاء
تنظيم الأمثلة بشكل منطقي
- ضع السيناريوهات الأكثر شيوعًا أولاً
- اجمع الأمثلة ذات الصلة معًا
- أزل الأمثلة القديمة لتجنب الارتباك
- قم بتحديث الأمثلة عندما تتغير API الخاصة بك
استخدم مفاتيح OAS بشكل فعال
- اختر مفاتيح ذات معنى تصف غرض المثال
- استخدم أنماط تسمية مفاتيح متسقة عبر API الخاص بك
- تجنب الأحرف الخاصة التي قد تسبب مشاكل في التصدير
من خلال متابعة هذه الممارسات، ستقوم بإنشاء أمثلة لجسم الطلب تساعد المطورين على فهم واستخدام API الخاص بك بفعالية.
الخاتمة
إضافة أمثلة متعددة لجسم الطلب في Apidog هي وسيلة بسيطة لكنها فعالة لتحسين وثائق API الخاصة بك. من خلال إظهار طرق مختلفة لبناء الطلبات لنفس نقطة النهاية، تساعد المطورين على فهم كيفية استخدام API في حالات مختلفة.
العملية خطوة بخطوة بسيطة:
- انتقل إلى نقطة النهاية الخاصة بك وانقر على "تعديل"
- قم بالتمرير إلى قسم جسم الطلب وانقر على "+ إضافة"
- قم بتكوين مثالك باسم، قيمة، وصف، ومفتاح OAS
- كرر ذلك من أجل السيناريوهات الإضافية
- استخدم أمثلتك للاختبار والتوثيق
مع إعداد الأمثلة المناسبة، يصبح API الخاص بك أسهل في الفهم والاختبار والتنفيذ. وهذا يؤدي إلى تبني أسرع، وأقل عدد من أسئلة الدعم، وتجربة أفضل للمطورين بشكل عام.
ابدأ في إضافة أمثلة متعددة لجسم الطلب إلى وثائق Apidog الخاصة بك اليوم لترى الفوائد بنفسك ولمستخدمي API لديك.