توليد Swagger/OpenAPI لـ PHP

توليد Swagger/OpenAPI لـ PHP: نظرة شاملة على الأدوات

في تطوير الويب الحديث، أصبح إنشاء توثيق عالي الجودة لواجهات API ليس مجرد سلوك حسن، بل ضرورة. Swagger (المعروف الآن باسم OpenAPI) هو معيار لوصف RESTful API، يتيح أتمتة توليد التوثيق، ومكتبات العملاء (SDK)، وواجهات الاختبار التفاعلية. في هذه المقالة، سنستعرض بالتفصيل كيفية استخدام Swagger/OpenAPI لمشاريع PHP، وما هي المكتبات المتاحة وكيفية دمجها بشكل صحيح.

ما هو Swagger/OpenAPI؟

OpenAPI Specification (OAS) هي مواصفات تحدد معيارًا لوصف REST API بتنسيق JSON أو YAML. تتيح ما يلي:

توليد توثيق تفاعلي تلقائيًا (Swagger UI)؛
إنشاء مكتبات عملاء بلغات برمجة مختلفة؛
التحقق من صحة الطلبات والاستجابات؛
التكامل مع خطوط أنابيب CI/CD.

المكتبات الرئيسية لـ PHP

للعمل مع OpenAPI في PHP، توجد عدة مكتبات شائعة. دعنا نستعرض كل منها بالتفصيل.

1. Swagger-PHP (zircote/swagger-php)

هذه هي المكتبة الأكثر شيوعًا ونضجًا لتوليد مواصفات OpenAPI من التعليقات التوضيحية (Annotations) في PHP. تتيح وصف API مباشرة داخل الكود، مما يبسط الحفاظ على التوثيق محدثًا.

التثبيت:

composer require zircote/swagger-php

مثال على الاستخدام:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="API الخاص بي", *     version="1.0.0", *     description="مثال API لعرض Swagger" * ) * @OA\\Server( *     url="https://api.example.com", *     description="خادم الإنتاج" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="الحصول على قائمة المستخدمين",     *     @OA\\Response(     *         response=200,     *         description="استجابة ناجحة",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // منطق الحصول على المستخدمين    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // طريقة فارغة لوصف المخطط    }}

// توليد المواصفات$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

هذه المكتبة لا تتيح فقط وصف API، بل أيضًا توليد كود الخادم تلقائيًا بناءً على مواصفات OpenAPI. وهي مفيدة بشكل خاص عند استخدام مبدأ التطوير القائم على التصميم (Design-First).

التثبيت:

composer require thecodingmachine/openapi-server

مثال على توليد الخادم:

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// تحميل المواصفات$spec = json_decode(file_get_contents('openapi.json'), true);

// إنشاء الخادم$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// معالجة الطلب$response = $server->handle($request);?>