Swagger-PHP لـ PHP: دليل شامل مع أمثلة عملية

1. ما هو Swagger-PHP ولماذا تحتاجه؟

Swagger-PHP هي مكتبة قوية للغة PHP تتيح لك إنشاء مواصفات OpenAPI (المعروفة سابقًا باسم Swagger) لواجهة REST API الخاصة بك تلقائيًا، وذلك بناءً على التعليقات التوضيحية (Annotations) الموجودة في الكود. بدلاً من كتابة ملفات YAML أو JSON ضخمة يدويًا لوصف جميع نقاط النهاية (Endpoints) والمعاملات (Parameters) ونماذج البيانات والاستجابات (Responses)، كل ما عليك فعله هو إضافة تعليقات خاصة (تعليقات توضيحية) مباشرة داخل وحدات التحكم (Controllers) والنماذج (Models) والمسارات (Routes) في تطبيق PHP الخاص بك. تقوم المكتبة بتحليل هذه التعليقات التوضيحية وإنشاء مواصفات OpenAPI كاملة وصالحة، يمكن تصديرها بتنسيق JSON أو YAML.

لماذا تحتاج هذا؟ في تطوير الويب الحديث، تعتبر واجهة API هي الواجهة الأساسية للتفاعل بين الواجهة الأمامية (Frontend) والتطبيقات المحمولة (Mobile Apps) والخدمات الخارجية. الحفاظ على تحديث التوثيق يمثل صداعًا دائمًا. Swagger-PHP يحل هذه المشكلة عن طريق ربط التوثيق مباشرة بالكود المصدري. إذا قمت بتغيير منطق نقطة نهاية معينة، فإنك تقوم أيضًا بتغيير التعليق التوضيحي المجاور لها. بهذه الطريقة، يظل التوثيق دائمًا متوافقًا مع السلوك الفعلي لواجهة API. هذا يوفر ساعات من العمل، ويقلل من أخطاء التكامل، ويجعل مشروعك واضحًا للمطورين الجدد.

علاوة على ذلك، يمكن استخدام مواصفات OpenAPI التي تم إنشاؤها مع عشرات الأدوات: Swagger UI (توثيق تفاعلي يمكنك من اختبار الطلبات مباشرة من المتصفح)، ومولدات SDK للعملاء بلغات مثل JavaScript وPython وJava وغيرها، وأدوات الاختبار والتحقق (مثل Postman أو Insomnia)، وكذلك لإنشاء خوادم وهمية (Mock Servers) تلقائيًا. Swagger-PHP هو المعيار الفعلي لتوثيق واجهات API في PHP.

2. التثبيت

يتم التثبيت عبر Composer، وهو مدير الحزم القياسي لـ PHP. قم بتنفيذ الأمر التالي في المجلد الجذر لمشروعك:

composer require zircote/swagger-php

بعد التثبيت، سيظهر مجلد vendor/zircote/swagger-php في مشروعك. تتطلب المكتبة إصدار PHP 8.0 أو أعلى (لدعم التعليقات التوضيحية الحديثة لـ PHP 8 Attributes). إذا كنت تستخدم إصدارًا أقدم من PHP، فستحتاج إلى إصدار 3.x من المكتبة، ولكن يُنصح بشدة بالترقية إلى PHP 8+ واستخدام أحدث إصدار من Swagger-PHP (4.x).

3. البداية السريعة — مثال عملي بسيط

لنقم بإنشاء وحدة تحكم بسيطة تحتوي على نقطة نهاية واحدة، ثم ننشئ لها مواصفات OpenAPI.

الخطوة 1: أنشئ ملف src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'الحصول على مستخدم بواسطة المعرف',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'استجابة ناجحة',
        content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'id', type: 'integer'),
                new OA\Property(property: 'name', type: 'string'),
                new OA\Property(property: 'email', type: 'string')
            ]
        )
    )]
    public function getUser(int $id): array
    {
        // هنا يجب أن يكون منطق الحصول على المستخدم من قاعدة البيانات
        return [
            'id' => $id,
            'name' => 'John Doe',
            'email' => 'john@example.com'
        ];
    }
}

الخطوة 2: أنشئ سكريبت لإنشاء المواصفات generate-docs.php

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OpenApi\Generator;

// حدد المجلد الذي يحتوي على وحدات التحكم مع التعليقات التوضيحية
$openapi = Generator::scan(['src/Controllers']);

// احفظ