عند فتح مستند واجهة برمجة تطبيقات (API) عبر الإنترنت منشور باستخدام Apidog، ستلاحظ زر "جربها" بجانب كل نقطة نهاية. يؤدي النقر عليه إلى ظهور لوحة تصحيح الأخطاء على الجانب الأيمن من الصفحة، مما يتيح لك اختبار واجهة برمجة التطبيقات مباشرة داخل الوثائق.
ومع ذلك، تعتمد قابلية استخدام ميزة "تصحيح الأخطاء" هذه بشكل كبير على مدى جودة تهيئتها داخل المنصة. تؤثر عوامل مثل إعداد عنوان URL الصحيح، وتهيئة المصادقة، وهيكل المعلمات الواضح، وبيانات الأمثلة الكاملة بشكل كبير على تجربة تصحيح الأخطاء.
إذا لم يتم تهيئتها بشكل صحيح، قد يقضي المستخدمون الكثير من الوقت في ملء المعلمات أو حتى يفشلون في إجراء استدعاءات ناجحة لواجهة برمجة التطبيقات، وهو أمر بعيد كل البعد عن المثالية.
دعنا نناقش كيفية تهيئة Apidog بفعالية لضمان أن توفر الوثائق المنشورة عبر الإنترنت تجربة تصحيح أخطاء ممتازة.
التهيئة الصحيحة لعنوان URL
غالبًا ما تبدو الوثائق عبر الإنترنت جيدة ولكنها تفشل عند النقر على زر "جربها" لإرسال طلب. السبب الأكثر شيوعًا هو أن نقطة النهاية تتضمن مسارًا فقط مثل /pet/{petId} دون تحديد بيئة تشغيل أثناء النشر.
يؤدي هذا إلى عناوين URL طلب غير مكتملة بدون بروتوكول أو اسم مضيف، مما يؤدي إلى أخطاء عند إرسال الطلبات.
لمعالجة هذا، تأكد من أن المستخدمين يمكنهم الوصول إلى عنوان URL الصحيح. يقدم Apidog ثلاث طرق لتهيئة عناوين URL للوثائق عبر الإنترنت، اعتمادًا على احتياجاتك.
1. استخدام عناوين URL الأساسية
هذا هو النهج الموصى به. قم بتعريف المسار فقط في نقطة النهاية، مثل /pet/{petId}، وقم بتهيئة عنوان الخدمة الكامل (على سبيل المثال، https://product.example.com) في قسم "إدارة البيئة" كعنوان URL أساسي.
عند نشر وثائق واجهة برمجة التطبيقات، حدد بيئة التشغيل المناسبة. سيقوم Apidog تلقائيًا بربط عنوان URL الأساسي بمسار نقطة النهاية. يمكنك أيضًا تعريف بيئات تشغيل متعددة، لكل منها عنوان URL أساسي خاص بها.
في الوثائق عبر الإنترنت، يمكن للمستخدمين التبديل بسرعة بين البيئات من قائمة منسدلة، وسيتم تحديث جميع عناوين URL لنقاط النهاية وفقًا لذلك. وهذا يجعل من السهل التحقق من صحة واجهات برمجة التطبيقات في بيئات مختلفة.
ملاحظة: انتبه لمشاكل البروتوكول. تمنع العديد من المتصفحات صفحات HTTPS من استدعاء واجهات برمجة تطبيقات HTTP. إذا كانت واجهة برمجة التطبيقات الخاصة بك تستخدم HTTP، فقد يواجه المستخدمون مشكلات عبر البروتوكولات عند تصحيح الأخطاء على صفحة وثائق HTTPS.
2. تضمين عناوين URL الكاملة في نقاط النهاية
خيار آخر هو تحديد عنوان URL الكامل مباشرة في نقطة النهاية، مثل https://product.example.com/pet/{petId}.
يضمن هذا أن يكون عنوان URL للطلب كاملاً ومرئيًا بغض النظر عن بيئة التشغيل المحددة. ومع ذلك، تصبح إدارة التغييرات على عناوين الخادم مرهقة حيث ستحتاج إلى تحديث كل نقطة نهاية على حدة. لذلك، هذه الطريقة أقل توصية.
3. استخدام المتغيرات في عناوين URL
إذا كنت تريد أن يقوم المستخدمون بتخصيص عنوان URL لتصحيح الأخطاء، يمكنك استخدام المتغيرات. على سبيل المثال، قم بإنشاء متغير بيئة BaseURL في قسم "إدارة البيئة" وقم بالإشارة إليه في عنوان URL الأساسي كـ {{BaseURL}}.
في الوثائق عبر الإنترنت، يمكن للمستخدمين النقر على اسم المتغير وتعديله إلى عنوان URL الذي يرغبون فيه.
بدلاً من ذلك، يمكنك تعريف المتغيرات مباشرة في نقطة النهاية، مثل {{BaseURL}}/pet/{petId}.
بالنسبة لنقطة النهاية المحددة تلك في الوثائق عبر الإنترنت، يمكن للمستخدمين تعيين قيمة المتغير لإرسال الطلب.
قبل نشر الوثائق، تأكد من أن "القيم الأولية" في البيئة لا تحتوي على معلومات حساسة (مثل بيانات اعتماد المصادقة)، حيث سيتم تضمين هذه القيم في الوثائق المنشورة وقد تشكل مخاطر على الخصوصية.
التهيئة الصحيحة للمصادقة
إعداد المصادقة الأساسية
غالبًا ما تتطلب طلبات نقطة النهاية الناجحة مصادقة. يدعم Apidog أنواعًا مختلفة من المصادقة، بما في ذلك رمز الحامل (Bearer Token)، مفتاح API (API Key)، OAuth2.0، والمصادقة الأساسية (Basic Auth).
يمكنك تهيئة المصادقة على مستوى نقطة النهاية أو المجلد باستخدام مخطط أمان أو عن طريق إعدادها يدويًا.
على سبيل المثال، عند استخدام رمز الحامل (Bearer Token) كنوع مصادقة، يظهر حقل "رمز" في الجزء العلوي من لوحة تصحيح الأخطاء في الوثائق عبر الإنترنت. يمكن للمستخدمين إدخال قيمة الرمز مباشرة دون إضافة بادئة "Bearer" يدويًا. يتعامل Apidog مع هذا تلقائيًا، مما يجعله أكثر ملاءمة من إضافة رأس ترخيص يدويًا.
ميزة هذا الإعداد هي أنه يمكن مشاركة معلومات المصادقة عبر نقاط نهاية متعددة. إذا كانت عدة نقاط نهاية تستخدم نفس مخطط الأمان أو النوع، فما عليك سوى إدخال بيانات الاعتماد مرة واحدة. وستطبق أي تحديثات على بيانات الاعتماد تلقائيًا على جميع نقاط النهاية المرتبطة.
يتم تشفير بيانات اعتماد المصادقة وتخزينها محليًا في متصفح المستخدم، وتتم إدارتها لكل جلسة، وتتم مشاركتها عبر علامات التبويب والنوافذ. ويتم مسحها عند إغلاق المتصفح، مما يقلل من خطر كشف المعلومات الحساسة في الوثائق المنشورة.
تهيئة OAuth2.0
بالنسبة لمصادقة OAuth2.0، إذا كنت تريد أن يقوم المستخدمون بإنشاء الرموز مباشرة أثناء تصحيح الأخطاء، فقم بتهيئة تفاصيل خادم التفويض (مثل عنوان URL للمصادقة، عنوان URL للرمز) في المشروع.
عند استخدام مخطط أمان OAuth2.0، سيحتاج المستخدمون إلى إدخال معرف العميل (client ID)، وسر العميل (client secret)، وما إلى ذلك، أثناء تصحيح الأخطاء. ستوجههم نافذة منبثقة خلال عملية التفويض، وسيتم تطبيق access_token الذي تم الحصول عليه تلقائيًا على طلبات واجهة برمجة التطبيقات اللاحقة.
تصميم هياكل معلمات واضحة
عرض المعلمات في لوحة تصحيح الأخطاء
تعرض لوحة تصحيح الأخطاء أقسام المعلمات بذكاء بناءً على تصميم نقطة النهاية الخاصة بك. على سبيل المثال، إذا كانت نقطة النهاية تحدد معلمات المسار (Path parameters) فقط، فستعرض لوحة تصحيح الأخطاء قسم المسار فقط، متجنبة أقسام الاستعلام (Query) أو الجسم (Body) غير الضرورية.
تساعد هذه الوضوح المستخدمين على فهم المعلمات التي يجب ملؤها دون تشتيت انتباههم بأقسام غير ذات صلة.
توفير مثال
عند تصميم نقاط النهاية، حدد نوع كل معلمة وخصائصها المطلوبة بدقة. قم بتضمين أوصاف وأمثلة واضحة، حيث سيتم ملء هذه المعلومات مسبقًا في لوحة تصحيح الأخطاء، مما يحسن قابلية الاستخدام.
تجنب الرؤوس الزائدة
إذا كانت نقطة النهاية تحدد معلمات الجسم (Body parameters)، فلا داعي لإضافة رؤوس يدويًا مثل Content-Type: application/json. يتعامل Apidog تلقائيًا مع هذه الرؤوس أثناء الطلبات.
وبالمثل، إذا تم تهيئة المصادقة، تجنب تكرارها في الرؤوس. إعدادات المصادقة لها الأسبقية وستتجاوز أي تهيئات رؤوس متعارضة.
تقديم أمثلة طلبات شاملة
بالنسبة لنقاط النهاية التي تحتوي على أجسام طلبات JSON معقدة، قم بتوفير أمثلة متعددة لأجسام الطلبات أثناء التصميم.
يمكن للمستخدمين تحديد هذه الأمثلة من قائمة منسدلة في لوحة تصحيح الأخطاء، مما يوفر الوقت ويقلل الأخطاء.
تأكد من أن بيانات الأمثلة تشبه إلى حد كبير السيناريوهات الواقعية، ولكن تجنب تضمين معلومات حساسة. يمكن للمستخدمين تعديل هذه الأمثلة حسب الحاجة.
تهيئة أمثلة استجابات واضحة
بعد إرسال الطلب، تعرض لوحة تصحيح الأخطاء الاستجابة الكاملة، بما في ذلك رموز الحالة والرؤوس والجسم. بصفتك منشئ وثائق، قم بتهيئة أمثلة استجابات واضحة لمساعدة المستخدمين على فهم النتائج المحتملة.
قم بتوفير أمثلة استجابات متعددة لكل نقطة نهاية، مثل النجاح (200)، والطلب الخاطئ (400)، وغير المصرح به (401).
انتبه بشكل خاص لاستجابات الأخطاء، مع شرح واضح لرموز الأخطاء وتنسيقات الرسائل للسيناريوهات المختلفة. يساعد هذا المستخدمين على تحديد المشكلات وحلها بسرعة أثناء تصحيح الأخطاء.
توفير رمز مثال للتكامل
بينما يقوم Apidog بتوليد رمز مثال تلقائيًا للغات البرمجة الشائعة، قد لا يتوافق الرمز المُولد تمامًا مع احتياجات عملك. في مثل هذه الحالات، قم بتخصيص الأمثلة.
يمكنك تهيئة اللغات التي تتطلب أمثلة مولدة تلقائيًا في "إعدادات المشروع -> إعدادات ميزة نقطة النهاية -> أمثلة رمز الطلب".
بالإضافة إلى ذلك، يمكنك كتابة رمز مثال مخصص لنقاط نهاية محددة في قسم "وصف نقطة النهاية".
يضمن هذا أن يرى المستخدمون كلاً من الأمثلة المولدة تلقائيًا والمخصصة في الوثائق عبر الإنترنت، مما يسهل عملية التكامل.
ملخص
تعتمد تجربة تصحيح الأخطاء للوثائق عبر الإنترنت بشكل كبير على التهيئة الصحيحة. من خلال إعداد عناوين URL، والمصادقة، وهياكل المعلمات، والأمثلة بعناية، يمكنك ضمان بدء المستخدمين بسرعة في استخدام واجهة برمجة التطبيقات الخاصة بك دون التعثر في التفاصيل الفنية.