Swagger-PHP هو أول شيء يتبادر إلى الذهن عند التفكير في إنشاء مواصفة Swagger لمشروع PHP. فما هو Swagger-PHP؟ كيف يمكنك إنشاء مواصفات باستخدام Swagger-PHP؟ في هذه المقالة، سنعالج هذه الأسئلة ونعرفكم على التفاصيل.

ما هو Swagger-PHP

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

ميزات Swagger-PHP

Swagger-PHP هي أداة قوية تستخدم لتوليد المواصفات لإصدارات OpenAPI 3.0 و3.1. كما أنها قادرة على تسجيل APIs باستخدام كود PHP المصدر. يمكن أن تكون خاصية التعليق المستخدمة في Swagger-PHP كتل doc أو PHP 8.1، مما يجعلها مرنة وقابلة للتكيف بشكل كبير.

سواء كنت تعمل مع كتل doc أو أحدث إصدار من PHP، يمكن أن يساعدك Swagger-PHP في تسريع عملية تطوير API وجعلها أكثر كفاءة بشكل عام.

كيفية التثبيت والإعداد في Swagger-PHP

لبدء استخدام Swagger-PHP، تحتاج إلى تثبيته أولاً. يمكن تثبيت Swagger-PHP باستخدام Composer، وهو مدير التبعيات لـ PHP.

لتثبيت Swagger-PHP، نفذ الأمر التالي في جهازك:

composer require zircote/swagger-php

بعد التثبيت، يمكنك البدء في استخدام Swagger-PHP لتوليد وثائق Swagger لـ API الخاص بك.

بعد ذلك، تحتاج إلى إعداد Swagger-PHP عن طريق إنشاء مثيل جديد من Swagger وتكوينه بمعلومات API الخاصة بك. إليك مثال على كيفية إعداد Swagger-PHP:

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="My API",
 *         description="وثائق API لـ My API",
 *         @SWG\Contact(name="My Company"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

في هذا المثال، قمنا بإنشاء مثيل جديد من Swagger وقمنا بتكوينه بمعلومات API الخاصة بنا، مثل المسار الأساسي، والأنظمة، ومعلومات API (الإصدار، العنوان، الوصف، الاتصال، والرخصة).

بعد إعداد Swagger-PHP، يمكنك البدء في إضافة تعليقات Swagger إلى كود API الخاص بك لتوليد وثائق Swagger. سنغطي هذا بمزيد من التفاصيل في القسم التالي.

إنشاء وثائق Swagger باستخدام Swagger-PHP

Swagger-PHP هو مكتبة PHP لتوليد وثائق Swagger. في هذا القسم، سنتعلم كيفية إنشاء وثائق Swagger باستخدام Swagger-PHP.

الخطوة 1. تعريف معلومات API

أولاً، نحتاج إلى تعريف معلومات API. يشمل ذلك العنوان، الوصف، الإصدار، إلخ من API. المثال التالي:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'هذه هي وثائق API نموذجية.',
        'version' => '1.0.0'
    ]);

الخطوة 2. تعريف نقاط نهاية API

بعد ذلك، نحتاج إلى تعريف نقاط نهاية API. يشمل ذلك طرق HTTP، والمسارات، والمعلمات والاستجابات لكل نقطة نهاية. المثال التالي:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'هذه هي وثائق API نموذجية.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'الحصول على قائمة بالمستخدمين.',
        'description' => 'يعود بقائمة من المستخدمين.',
        'responses' => [
            '200' => [
                'description' => 'قائمة من المستخدمين.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'إنشاء مستخدم جديد.',
        'description' => 'ينشئ مستخدمًا جديدًا.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'المستخدم الذي سيتم إنشاؤه.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'المستخدم المنشأ.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

الخطوة 3. تعريف نموذج البيانات

أخيرًا، نحتاج إلى تعريف نماذج البيانات. يشمل ذلك السمات وأنواع كل نموذج. المثال التالي:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'هذه هي وثائق API نموذجية.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'الحصول على قائمة بالمستخدمين.',
        'description' => 'يعود بقائمة من المستخدمين.',
        'responses' => [
            '200' => [
                'description' => 'قائمة من المستخدمين.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'إنشاء مستخدم جديد.',
        'description' => 'ينشئ مستخدمًا جديدًا.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'المستخدم الذي سيتم إنشاؤه.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'المستخدم المنشأ.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

الخطوة 4. تصدير وثائق Swagger

أخيرًا، يمكننا إخراج وثائق Swagger باستخدام الكود التالي:

header('Content-Type: application/json');
echo $swagger->toJson();

ستخرج هذه وثيقة Swagger بتنسيق JSON يمكن استخدامها لتوليد وثائق API.

دمج Swagger UI مع Swagger-PHP

للاستفادة الكاملة من فوائد وثائق Swagger، من المهم أن يكون لديك واجهة سهلة الاستخدام لعرض والتفاعل مع الوثائق. هنا يأتي دور Swagger-UI. Swagger-UI هي واجهة قائمة على الويب توفر تجربة تفاعلية لعرض واختبار وثائق Swagger.

دمج Swagger-UI مع Swagger-PHP هو عملية مباشرة. أولاً، قم بتنزيل أحدث إصدار من Swagger-UI من المستودع الرسمي على GitHub. ثم، استخرج محتويات الأرشيف الذي تم تنزيله إلى دليل على خادم الويب الخاص بك.

بعد ذلك، قم بإنشاء ملف PHP جديد سيكون بمثابة نقطة الدخول لـ Swagger-UI. في هذا الملف، أضف ملفات CSS وJavaScript اللازمة لـ Swagger-UI، بالإضافة إلى مكتبة JavaScript الخاصة بـ Swagger-UI نفسها. ستحتاج أيضًا إلى تضمين ملف JSON الناتج عن Swagger-PHP الذي يحتوي على وثائق API الخاصة بك.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // بناء نظام
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

في المثال أعلاه، استبدل path/to بالمسارات الفعلية إلى ملفات CSS وJavaScript الخاصة بـ Swagger-UI، بالإضافة إلى ملف JSON الناتج عن Swagger-PHP.

بمجرد إنشاء هذا الملف، يمكنك الوصول إلى Swagger-UI عن طريق الانتقال إلى عنوانه في متصفح الويب الخاص بك. يجب أن ترى واجهة Swagger-UI بالكامل التي تعرض وثائق API الخاصة بك وتتيح لك التفاعل معها.

باختصار، يعد دمج Swagger-UI مع Swagger-PHP عملية بسيطة تعزز بشكل كبير من سهولة استخدام وثائق API الخاصة بك. باتباع الخطوات الموضحة أعلاه، يمكنك بسهولة إنشاء واجهة سهلة الاستخدام لوثائق API الخاصة بك ستجعل من السهل على المطورين فهم واستخدام API الخاص بك.

شارك مواصفات API

بعد توليد مواصفة Swagger، غالبًا ما أشاركها مع أعضاء فريقي. في هذه الحالات، غالبًا ما نشاركها بصيغة JSON الخاصة بـ Swagger أو صيغة YAML لإصدار OpenAPI، ولكن يبدو أن ذلك قديم بعض الشيء.

هنا يعتبر Apidog أداة إدارة API المثالية التي تولد على الفور مواصفات API قابلة للقراءة بناءً على بيانات JSON أو YAML من Swagger. يمكنك أيضًا بسهولة مشاركة هذه المواصفة باستخدام وظيفة مشاركة API.

يقدم Apidog أيضًا وظائف متنوعة كأداة لإدارة دورة حياة API.

تصميم API وتوليد المواصفات: يعد Apidog أسهل أداة لتصميم API، مما يسمح لك بتصميم APIs بشكل حدسي دون الحاجة إلى كود، وتوليد مواصفات OpenAPI وSwagger بشكل مريح.

إدارة API واختبار الوحدة: تجعل Apidog اختبار الوحدة سهلًا جدًا حيث يمكنك إدارة API الخاص بك بكفاءة، وإرسال طلبات API والتحقق من الاستجابات.

أتمتة اختبار API: يدعم Apidog أيضًا الاختبار التلقائي وهو جاهز لـ CI/CD. من خلال استخدام هذه الوظيفة لتعيين عدد من الخيوط، إلخ، يمكنك بسهولة تنفيذ اختبارات تحميل API وأتمتة اختبار API.

الخاتمة

في الختام، يعد Swagger-PHP أداة قوية لتوليد وثائق Swagger لـ APIs المعتمدة على PHP. يتيح ذلك للمطورين وثائق API الخاصة بهم بسهولة وجعلها متاحة لمطورين آخرين. بالإضافة إلى ذلك، يوفر دمج Swagger-UI مع Swagger-PHP واجهة سهلة الاستخدام لاستكشاف واختبار APIs.

إليك بعض الموارد لمزيد من التعلم حول Swagger-PHP:

• التوثيق الرسمي: https://zircote.github.io/swagger-php/
• مستودع GitHub: https://github.com/zircote/swagger-php
• Swagger-UI: https://swagger.io/tools/swagger-ui/