جدول المحتويات

1. المقدمة
2. ما هو Laravel Scribe؟
3. التثبيت
4. التكوين
5. إنشاء التوثيق
6. تخصيص التوثيق
7. الخاتمة

المقدمة

تخيل أنك انتهيت للتو من تطوير REST API لمشروع ما. ما هي الخطوة التالية؟ يمكن أن تكون عملية التوثيق اليدوي مملة وعرضة للأخطاء وتستغرق وقتًا طويلًا. هنا يأتي دور Scribe—حزمة Laravel رائعة تنشئ توثيق واجهات API تلقائيًا.

ما الذي يتناوله هذا المقال:

1. لماذا يعد Scribe مفيدًا.
2. كيفية تثبيته وتهيئته واستخدامه.
3. أمثلة عملية من الاستخدام في الواقع العملي.

ما هو Laravel Scribe؟

Laravel Scribe هو حزمة تقوم تلقائيًا بإنشاء توثيق لواجهات برمجة التطبيقات (API) من خلال مسارات Laravel. يستخرج المعلومات من وحدات التحكم (Controllers)، طلبات النماذج (Form Requests)، والمكونات الأخرى لإنشاء توثيق تفصيلي. يتضمن هذا التوثيق النقاط الطرفية (Endpoints)، معاملات الطلبات، أمثلة الاستجابات، والمزيد.

التثبيت

لبدء استخدام Laravel Scribe، تحتاج إلى تثبيته عبر Composer. قم بتنفيذ الأمر التالي في الطرفية:

composer require --dev knuckleswtf/scribe

بعد تثبيت الحزمة، يمكنك نشر ملف التكوين باستخدام:

php artisan vendor:publish --tag=scribe-config

سيؤدي هذا إلى إنشاء ملف scribe.php في مجلد config.

التكوين

يسمح ملف scribe.php بتخصيص جوانب مختلفة من توثيق واجهة برمجة التطبيقات. بعض الإعدادات الرئيسية تشمل:

• title: عنوان توثيق واجهة برمجة التطبيقات.
• description: وصف مختصر لواجهة برمجة التطبيقات.
• base_url: الرابط الأساسي لواجهة برمجة التطبيقات.
• routes: تحديد المسارات التي يجب تضمينها في التوثيق.

إليك مثال على التكوين:

return [
    'title' => 'توثيق واجهة برمجة التطبيقات الخاصة بي',
    'description' => 'هذا هو توثيق واجهة برمجة التطبيقات لتطبيقي.',
    'base_url' => env('APP_URL'),
    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
            ],
            'include' => [],
            'exclude' => [],
        ],
    ],
];

إنشاء التوثيق

بعد تكوين Laravel Scribe، يمكنك إنشاء التوثيق عن طريق تنفيذ الأمر التالي:

php artisan scribe:generate

سيؤدي هذا الأمر إلى إنشاء مجموعة من ملفات HTML ثابتة في مجلد public/docs بشكل افتراضي. يمكنك الوصول إلى التوثيق من خلال زيارة الرابط http://your-app-url/docs.

تخصيص التوثيق

يسمح Laravel Scribe بتخصيص التوثيق عن طريق إضافة التعليقات التوضيحية (Annotations) إلى وحدات التحكم والطرق. إليك بعض التعليقات التوضيحية الشائعة:

• @group: يجمع النقاط الطرفية ذات الصلة معًا.
• @bodyParam: يصف معاملات جسم الطلب.
• @response: يوفر مثالاً للاستجابة.

إليك مثال لطريقة في وحدة التحكم مع التعليقات التوضيحية:

/**
 * @group إدارة المستخدمين
 *
 * تسجيل مستخدم جديد.
 *
 * @bodyParam name string required اسم المستخدم. مثال: Akram Ghaleb
 * @bodyParam email string required البريد الإلكتروني للمستخدم. مثال: akram@example.com
 * @bodyParam password string required كلمة مرور المستخدم. مثال: password123
 *
 * @response 200 {
 *     "message": "تم تسجيل المستخدم بنجاح",
 *     "user": {
 *         "id": 1,
 *         "name": "Akram Ghaleb",
 *         "email": "akram@example.com"
 *     }
 * }
 */
public function register(Request $request)
{
    // منطق التسجيل هنا
}

الخاتمة

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

برمجة موفقة! 🚀