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

تمت الكتابة بواسطة: عبد الحكيم

تارخ آخر تحديث: 19 ديسمبر 2024

محتوى المقال

ما هو Swagger؟
لماذا نستخدم Swagger لتوثيق API؟
إعداد بيئة PHP لتوثيق API باستخدام Swagger
إضافة تعليقات التوثيق إلى API الخاص بك
إنشاء ملف توثيق API
عرض التوثيق باستخدام Swagger UI
الخلاصة

تعتبر واجهات برمجة التطبيقات (APIs) جزءًا أساسيًا من تطوير الويب الحديث، وتوثيق هذه الواجهات يعد أمرًا بالغ الأهمية لضمان استخدامها بشكل صحيح وفعال. Swagger هو إطار عمل قوي يمكن استخدامه لتوثيق APIs بطريقة واضحة ومنظمة. في هذا المقال، سنتعرف على كيفية استخدام Swagger مع PHP لإنشاء توثيق مفصل لواجهات برمجة التطبيقات الخاصة بك.

ما هو Swagger؟

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

لماذا نستخدم Swagger لتوثيق API؟

يقدم Swagger العديد من الفوائد عند توثيق API:

سهولة الاستخدام: يتيح Swagger للمطورين فهم كيفية استخدام API بسرعة من خلال توثيق تفاعلي.
التحديث التلقائي: يمكن ربط Swagger بالكود الخاص بك بحيث يتم تحديث التوثيق تلقائيًا عند إجراء تغييرات على API.
التوافق مع RESTful: تم تصميم Swagger خصيصًا لتوثيق RESTful APIs.

إعداد بيئة PHP لتوثيق API باستخدام Swagger

للبدء باستخدام Swagger مع PHP، نحتاج إلى تثبيت مكتبة zircote/swagger-php التي توفر أدوات لتوليد ملفات التوثيق من تعليقات الكود.


        composer require zircote/swagger-php

إضافة تعليقات التوثيق إلى API الخاص بك

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


        <?php

        /**

         * @OA\Info(title="API Example", version="1.0.0")

         */


        /**

         * @OA\Get(

         *     path="/api/user",

         *     @OA\Response(response="200", description="Fetch user data")

         * )

         */

        function getUserData() {

           // كود لاسترجاع بيانات المستخدم

           echo '{"name": "أحمد", "age": 25}';

        }

        ?>

في هذا المثال، نستخدم تعليقات @OA\Info لتعريف معلومات الـ API العامة مثل العنوان والإصدار، وتعليقات @OA\Get لتوثيق نقطة نهاية API معينة.

إنشاء ملف توثيق API

بعد إضافة التعليقات إلى الكود الخاص بك، يمكنك توليد ملف توثيق JSON باستخدام أمر بسيط:


        vendor/bin/openapi --output swagger.json /path/to/your/php/files

سيقوم هذا الأمر بفحص الملفات المحددة وتوليد ملف swagger.json الذي يحتوي على توثيق الـ API بناءً على التعليقات التي قمت بإضافتها.

عرض التوثيق باستخدام Swagger UI

Swagger UI هو واجهة تفاعلية تتيح لك عرض واستكشاف توثيق API الخاص بك بسهولة. يمكنك استخدام Swagger UI لعرض ملف swagger.json الخاص بك بشكل تفاعلي.

لتثبيت Swagger UI محليًا، يمكنك اتباع الخطوات التالية:

قم بتنزيل Swagger UI من مستودع GitHub الخاص بهم.
قم بوضع ملف swagger.json في مجلد dist الخاص بـ Swagger UI.
افتح ملف index.html الخاص بـ Swagger UI في متصفحك.

الخلاصة

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