توليد Swagger/OpenAPI لـ PHP: أفضل الأدوات والمكتبات

توليد Swagger/OpenAPI لـ PHP: أتمتة توثيق API

\n\n

Swagger (الآن OpenAPI) هو معيار لوصف RESTful API، يسمح للمطورين والعملاء والأدوات الآلية بفهم إمكانيات الخدمة دون الوصول إلى الكود المصدري. لمطوري PHP، الأداة الرئيسية هي مكتبة zircote/swagger-php (المعروفة سابقًا باسم swagger-php)، والتي تولد تلقائيًا مواصفات OpenAPI من التعليقات التوضيحية في الكود.

\n\n

ما هي zircote/swagger-php؟

\n\n

هذه هي المكتبة الأساسية لتوليد مواصفات OpenAPI في PHP. تقوم بتحليل تعليقات PHPDoc التوضيحية في المتحكمات (Controllers) والنماذج (Models) والمسارات (Routes)، لإنشاء ملف JSON/YAML يمكن استخدامه من أجل:

\n\n

\n
• التوليد التلقائي للتوثيق (Swagger UI, ReDoc)
\n
• توليد مكتبات العميل (Client Libraries) للغات مختلفة
\n
• اختبار API (Postman, Insomnia)
\n
• التحقق من صحة الطلبات والاستجابات
\n

\n\n

التثبيت والإعداد

\n\n

التثبيت عبر Composer:

\n\n

composer require zircote/swagger-php

\n\n

يتضمن الحد الأدنى من التكوين لـ Laravel (أو أي إطار عمل) إنشاء تعليقات توضيحية في المتحكم. مثال لمتحكم بسيط مع تعليقات OpenAPI التوضيحية:

\n\n

<?php\n\nnamespace App\\Http\\Controllers\\Api;\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Info(title="My API", version="1.0.0")\n * @OA\\Server(url="https://api.example.com")\n */\nclass UserController extends Controller\n{\n    /**\n     * @OA\\Get(\n     *     path="/api/users/{id}",\n     *     summary="الحصول على مستخدم بواسطة المعرف",\n     *     @OA\\Parameter(\n     *         name="id",\n     *         in="path",\n     *         required=true,\n     *         @OA\\Schema(type="integer")\n     *     ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description="استجابة ناجحة",\n     *         @OA\\JsonContent(ref="#/components/schemas/User")\n     *     ),\n     *     @OA\\Response(response=404, description="المستخدم غير موجود")\n     * )\n     */\n    public function show($id)\n    {\n        // المنطق\n    }\n}

\n\n

توليد المواصفات

\n\n

لإنشاء ملف OpenAPI، قم بتنفيذ الأمر:

\n\n

vendor/bin/openapi src -o public/openapi.yaml

\n\n

أو استخدم كود PHP:

\n\n

<?php\n\nuse OpenApi\\Generator;\n\n$openapi = Generator::scan(['/path/to/project/src']);\nfile_put_contents('public/openapi.json', $openapi->toJson());

\n\n

الإمكانيات المتقدمة

\n\n

تدعم المكتبة:

\n\n

\n
• المخططات المتداخلة — الإنشاء التلقائي للنماذج من التعليقات التوضيحية
\n
• تجميع نقاط النهاية عبر @OA\\Tag
\n
• الأمان — @OA\\SecurityScheme لـ JWT, OAuth2
\n
• أمثلة الطلبات — @OA\\RequestBody مع أمثلة
\n

\n\n

مثال لنموذج مع تعليقات توضيحية:

\n\n

<?php\n\n/**\n * @OA\\Schema(\n *     schema="User",\n *     required={"id", "email"},\n *     @OA\\Property(property="id", type="integer", format="int64"),\n *     @OA\\Property(property="email", type="string", format="email"),\n *     @OA\\Property(property="name", type="string"),\n *     @OA\\Property(property="created_at", type="string", format="date-time")\n * )\n */\nclass User\n{\n    // الخصائص\n}

\n\n

التكامل مع أطر العمل

\n\n

بالنسبة لـ Laravel، توجد حزمة darkaonline/l5-swagger، والتي تضيف:

\n\n

\n
• التوليد التلقائي مع كل طلب
\n
• واجهة Swagger UI مدمجة
\n
• التكوين عبر ملف config
\n

\n\n

التثبيت:

\n\n

composer require darkaonline/l5-swagger\nphp artisan vendor:publish --provider="L5Swagger\\L5SwaggerServiceProvider"

\n\n

بالنسبة لـ Symfony، استخدم nelmio/api-doc-bundle.

\n\n

مقارنة