اكتشف فريق تطوير Go في إحدى الشركات التقنية مؤخراً أن Swagger UI أدى إلى توثيق غير دقيق، تجربة مستخدم سيئة، ومشاكل مستمرة في الإعدادات. لذلك، قرروا الانتقال إلى Scalar للحصول على حل أفضل لتوثيق واجهة برمجة التطبيقات الخاصة بهم.
مرحباً أيها مطورو Go، كشفت حقيقة حديثة من فريق تقني عن نقطة ألم شائعة: يتخلى الكثيرون عن Swagger UI لصالح حلول أكثر حداثة مثل Scalar لتوثيق واجهة برمجة التطبيقات (API). ما يعنيه هذا لكم هو أنه إذا كنتم تواجهون صعوبات مع توثيق واجهة برمجة التطبيقات الخاصة بكم، فهناك خيارات أفضل وأقل إحباطاً متاحة.
هذا الفريق، مثل العديد من الفرق الأخرى، اتبع الطريقة المعتادة في Go لسنوات: كتابة تعليقات مفصلة فوق المعالجات، تشغيل `swag init`، وتركيب Swagger UI. لقد نجح الأمر بشكل جيد عندما كان نظامهم الخلفي صغيراً، ولكن مع نموه، تحول إلى كابوس. في أحد أيام الجمعة، اكتشف مهندس الواجهة الأمامية أن ساحة اختبار واجهة برمجة التطبيقات الخاصة بهم على بيئة الاختبار كانت تحاول إرسال الطلبات إلى `localhost:8080` – وهو سيناريو كلاسيكي لمشكلة 'يعمل على جهازي!' كشف عن عيوب عميقة في إعدادات التوثيق لديهم.
لقد واجهوا ثلاث مشاكل رئيسية يومياً مع Swagger UI. أولاً، كان الحفاظ على دقة التوثيق معركة مستمرة. إذا قمت بإعادة هيكلة Go struct ونسيت تحديث 'التعليقات السحرية' فوق معالج HTTP الخاص بك، فإن التوثيق سيحتوي على معلومات خاطئة. على سبيل المثال، قد يزعم التوثيق أن نقطة النهاية تعيد سلسلة نصية بسيطة بينما يعيد رمزك الفعلي كائن JSON معقداً. أدى ذلك إلى قضاء فريق الواجهة الأمامية ساعات في تصحيح الأخطاء، غير مدركين لعدم تطابق التوثيق مع الكود.
ثانياً، كانت تجربة المستخدم قديمة بشكل لا يصدق. لنكن صريحين، كان Swagger UI يبدو وكأنه صُمم عندما كان Internet Explorer 8 لا يزال موجوداً. محاولة اختبار نقاط النهاية التي تتطلب مصادقة JWT، أو التنقل في مخططات أخطاء JSON المتداخلة، أو البحث عبر عشرات نقاط النهاية، كانت عملية مؤلمة، أشبه بالتعامل مع مواقع الويب الحكومية القديمة.
أخيراً، كان تحديد واجهة برمجة التطبيقات الذي يتم إنشاؤه يتضمن غالباً `host: "localhost:8080"`. هذا يعني أنه عندما حاول فريق ضمان الجودة اختبار استدعاءات واجهة برمجة التطبيقات على بيئة الاختبار، فشلت كل نقرة على زر 'جربه' بصمت، مرسلةً الطلبات إلى خادم محلي غير موجود. أهدرت هذه المشاكل ساعات لا تحصى وأدت إلى نقاشات محبطة حول سبب عدم عمل الأمور. ساعدهم الانتقال إلى Scalar في التغلب على هذه المشكلات الحرجة، مما يشير إلى مسار أوضح لتوثيق أفضل لواجهة برمجة التطبيقات.
هذا الفريق، مثل العديد من الفرق الأخرى، اتبع الطريقة المعتادة في Go لسنوات: كتابة تعليقات مفصلة فوق المعالجات، تشغيل `swag init`، وتركيب Swagger UI. لقد نجح الأمر بشكل جيد عندما كان نظامهم الخلفي صغيراً، ولكن مع نموه، تحول إلى كابوس. في أحد أيام الجمعة، اكتشف مهندس الواجهة الأمامية أن ساحة اختبار واجهة برمجة التطبيقات الخاصة بهم على بيئة الاختبار كانت تحاول إرسال الطلبات إلى `localhost:8080` – وهو سيناريو كلاسيكي لمشكلة 'يعمل على جهازي!' كشف عن عيوب عميقة في إعدادات التوثيق لديهم.
لقد واجهوا ثلاث مشاكل رئيسية يومياً مع Swagger UI. أولاً، كان الحفاظ على دقة التوثيق معركة مستمرة. إذا قمت بإعادة هيكلة Go struct ونسيت تحديث 'التعليقات السحرية' فوق معالج HTTP الخاص بك، فإن التوثيق سيحتوي على معلومات خاطئة. على سبيل المثال، قد يزعم التوثيق أن نقطة النهاية تعيد سلسلة نصية بسيطة بينما يعيد رمزك الفعلي كائن JSON معقداً. أدى ذلك إلى قضاء فريق الواجهة الأمامية ساعات في تصحيح الأخطاء، غير مدركين لعدم تطابق التوثيق مع الكود.
ثانياً، كانت تجربة المستخدم قديمة بشكل لا يصدق. لنكن صريحين، كان Swagger UI يبدو وكأنه صُمم عندما كان Internet Explorer 8 لا يزال موجوداً. محاولة اختبار نقاط النهاية التي تتطلب مصادقة JWT، أو التنقل في مخططات أخطاء JSON المتداخلة، أو البحث عبر عشرات نقاط النهاية، كانت عملية مؤلمة، أشبه بالتعامل مع مواقع الويب الحكومية القديمة.
أخيراً، كان تحديد واجهة برمجة التطبيقات الذي يتم إنشاؤه يتضمن غالباً `host: "localhost:8080"`. هذا يعني أنه عندما حاول فريق ضمان الجودة اختبار استدعاءات واجهة برمجة التطبيقات على بيئة الاختبار، فشلت كل نقرة على زر 'جربه' بصمت، مرسلةً الطلبات إلى خادم محلي غير موجود. أهدرت هذه المشاكل ساعات لا تحصى وأدت إلى نقاشات محبطة حول سبب عدم عمل الأمور. ساعدهم الانتقال إلى Scalar في التغلب على هذه المشكلات الحرجة، مما يشير إلى مسار أوضح لتوثيق أفضل لواجهة برمجة التطبيقات.
