كيفية إنشاء توثيق سواجر باستخدام سواجر-بي اتش بي

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

Amir Hassan

Amir Hassan

21 أغسطس 2025

كيفية إنشاء توثيق سواجر باستخدام سواجر-بي اتش بي

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

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

يقدم 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:

Explore more

ما هي بيئات Docker المعزولة؟ وكيف يعزل Docker وكلاء البرمجة بالذكاء الاصطناعي

ما هي بيئات Docker المعزولة؟ وكيف يعزل Docker وكلاء البرمجة بالذكاء الاصطناعي

تُشغّل Docker Sandboxes أدوات مثل Claude Code وCodex وغيرها من وكلاء البرمجة داخل بيئات microVM بنواة وشبكة ومحرك Docker خاص بها. اكتشف كيف يعمل العزل والإعداد والسياسات والتسعير وحوكمة الذكاء الاصطناعي.

20 نوفمبر 2026

Codex Sandbox مقابل Docker Sandboxes: طريقتان لعزل وكيل البرمجة

Codex Sandbox مقابل Docker Sandboxes: طريقتان لعزل وكيل البرمجة

تقيّد OpenAI أوامر Codex على جهازك باستخدام العزل الأمني على مستوى نظام التشغيل، بينما تشغّل Docker الوكلاء داخل microVMs. قارن من حيث العزل والأدوات الأصلية والتحكم في الشبكة وسياسة الفريق، واكتشف متى ينبغي الجمع بينهما.

20 نوفمبر 2026

ملفات تعريف أذونات Codex: أمثلة config.toml لتشغيل الوكلاء بأمان

ملفات تعريف أذونات Codex: أمثلة config.toml لتشغيل الوكلاء بأمان

تحدد ملفات تعريف الأذونات في Codex ما يمكن لأوامر وكيلك قراءته وكتابته والوصول إليه. إليك أمثلة config.toml تم اختبارها، بما في ذلك ملف تعريف للعمل على API يشغّل Apidog CLI دون إنترنت مفتوح.

20 نوفمبر 2026

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات