كل المنشورات / Laravel / №03
توثيق الـ APIs في Laravel بلا تعليقات: l5-swagger أم Scramble؟
مع l5-swagger تكتب تعليقات فوق كل Controller وكل دالة وكل مُدخل واستجابة. أما Scramble فيقرأ الـ Controllers وطلبات النماذج وقواعد التحقق، ويولّد التوثيق وحده.
في مشكلة بلارافيل تقريبًا الكل بيشتكي منها بوسط الشغل…
إلا وهي API Docs Generators 😵💫
أول ما تفكر تعمل API Docs لـ REST APIs
رح تسمع اكيد ب: l5-swagger
بيعطيك Swagger UI
واجهة معروفة، ممتازة لتجربة الـ APIs
بس المشكلة الحقيقية مو بالواجهة…
المشكلة بـ كمية التعليقات (Annotations) الي لازم تكتبها 🤯
بدك:
- تعليقات فوق كل Controller
- تعليقات فوق كل Method
- تعليقات للـ params
- تعليقات للـ responses
يعني تقريبًا عم تكتب Controller ثاني… بس بالتعليقات.
هلق طبعا ال AI بهالايام خفف هالعبئ وساعد بالموضوع...
بس الصراحة لساته الموضوع مزعج ومتعب، خصوصًا بمشاريع كبيرة.
وبهالوقت نفسه:
كانت NestJS عم تنتشر
وحلت هالمشكلة بطريقة أنضف
فكثير مطورين (حتى Seniors) كرهوا القصة… وقلّبوا Nest (طبعا في اسباب تانية بس هي القصة كتير خلتهم يكرهوا Laravel).
بلا طول سيرة ... بيوم من الأيام، وأنا عم دور على حل،
لقيت package اسمها Scramble
هي المكتبة بتعمل سحر حقيقي ✨
بتقرأ الكود كامل بمافيه: Controllers - Requests - Validators - Services
وبتطلعلك API Docs حلوة وواضحة
بدون ما تكتب ولا تعليق.
بتفهم Validators - Form Requests - Schemas وبتولد كلشي لحالها.
طبعا أكيد، إذا بدك تغيّر عنوان Endpoint أو توصف شي بشكل خاص بدك تعليق صغير
بس مقارنة بـ l5-swagger؟
فرق بين السما والأرض.
مهما تطورت NestJS
لساته عندي إيمان كبير بـ Laravel
وبالسحر تبعها ❤️
ومع أدوات متل Scramble
Laravel قادرة تنافس…
وتتفوق.