دليل Swagger-PHP لـ PHP: شرح كامل مع أمثلة تطبيقية

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

Swagger-PHP هي مكتبة PHP قوية لتوليد توثيق REST API تلقائيًا بصيغة OpenAPI (المعروفة سابقًا باسم Swagger). بدلاً من كتابة التوثيق يدويًا في YAML أو JSON، يمكنك وصف API مباشرة في الكود باستخدام تعليقات PHPDoc التوضيحية. تقوم المكتبة بتحليل هذه التعليقات وتوليد مواصفات OpenAPI كاملة، يمكن عرضها باستخدام Swagger UI أو ReDoc أو أدوات أخرى.

لماذا تحتاج إليه؟

• أتمتة: التوثيق دائمًا متزامن مع الكود. غيّر endpoint — حدّث التعليق التوضيحي، والتوثيق جاهز.
• توحيد المعايير: OpenAPI هو المعيار الصناعي لوصف REST API، مدعوم بمئات الأدوات.
• سهولة للواجهة الأمامية: يمكن لمطوري التطبيقات العميلة استيراد المواصفات إلى Postman أو Insomnia أو توليد كود عميل.
• الاختبار: يمكن استخدام المواصفات لاختبار API تلقائيًا.
• توثيق تفاعلي: يتيح Swagger UI اختبار endpoints مباشرة من المتصفح.

تثبيت Swagger-PHP

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

composer require zircote/swagger-php

إذا كنت تستخدم Laravel أو Symfony أو أي إطار عمل آخر، فإن التثبيت لا يختلف. بعد التثبيت، سيظهر مجلد vendor/zircote/swagger-php في مشروعك.

إضافي (اختياري): لعرض التوثيق، ستحتاج إلى Swagger UI. يمكنك تثبيته عبر npm:

npm install swagger-ui-dist

أو ببساطة قم بتنزيل الإصدار الجاهز من الموقع الرسمي لـ Swagger.

بداية سريعة مع مثال كود

لنقم بإنشاء API بسيط لإدارة قائمة المهام (Todo List) وتوليد التوثيق له.

الخطوة 1: أنشئ ملف index.php مع API الخاص بك:

<?php
/**
 * @OA\Info(
 *     title="Todo API",
 *     version="1.0.0",
 *     description="API بسيط لإدارة المهام"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="الخادم المحلي"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="الحصول على قائمة بجميع المهام",
 *     @OA\Response(
 *         response=200,
 *         description="استجابة ناجحة",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'شراء حليب', 'completed' => false],
        ['id' => 2, 'title' => 'كتابة مقال', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="إنشاء مهمة جديدة",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="تم إنشاء المهمة",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // منطق إنشاء المهمة
    echo json_encode(['id' => 3, 'title' => 'مهمة جديدة', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// توجيه بسيط
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQ