دليل Swagger: ما هو واجهة Swagger وكيفية استخدام Swagger

Swagger UI هو أداة مفتوحة المصدر لتصور والتفاعل مع واجهات برمجة التطبيقات RESTful. في هذا الدليل، سنعرض لك المقدمة الأساسية لـ Swagger وكيفية استخدام Swagger UI لاختبار واجهة برمجة التطبيقات.

Amir Hassan

Amir Hassan

28 مايو 2025

دليل Swagger: ما هو واجهة Swagger وكيفية استخدام Swagger

ما هو Swagger UI؟

Swagger UI هو أداة مفتوحة المصدر لتصوير والتفاعل مع واجهات برمجة التطبيقات RESTful (واجهات برمجة التطبيقات) التي تم توثيقها باستخدام OpenAPI Specification (المعروفة سابقًا باسم Swagger Specification).

OpenAPI Specification هو تنسيق قياسي لوصف واجهات برمجة التطبيقات RESTful بتنسيق يمكن للآلة قراءته. يسهل Swagger UI استكشاف واختبار هذه الواجهات، من خلال توفير واجهة سهلة الاستخدام للمطورين لتصفح توثيق واجهة برمجة التطبيقات، واختبار نقاط نهاية واجهة برمجة التطبيقات، وتجربة مع معلمات وخيارات مختلفة.

Swagger

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

ميزات Swagger UI:

بشكل عام، يعد Swagger UI أداة قوية ومرنة للعمل مع واجهات برمجة التطبيقات RESTful، وقد أصبح اختيارًا شائعًا بين المطورين ومقدمي واجهات برمجة التطبيقات لاختبار واجهات برمجة التطبيقات الخاصة بهم.

ما هو استخدام Swagger UI؟

القيود على Swagger UI

Swagger UI هو أداة مفيدة لعرض توثيق واجهات برمجة التطبيقات ويقدم ميزات لمساعدتك في تصميم واختبار واجهات برمجة التطبيقات الخاصة بك، ولكنه بعيد عن أن يكون أداة إدارة واجهات برمجة التطبيقات كاملة. إليك السبب.

  1. عدم القدرة على تلبية متطلبات إدارة واجهات برمجة التطبيقات الواسعة: يركز Swagger UI على عرض واختبار توثيق واجهة برمجة التطبيقات ولا يغطي جميع الميزات المطلوبة لإدارة واجهات برمجة التطبيقات. هناك العديد من جوانب إدارة واجهات برمجة التطبيقات مثل إدارة دورة حياة واجهة برمجة التطبيقات، والتحكم في الإصدارات، والمصادقة/التفويض، ومراقبة الأداء، وإدارة الأمان.
  2. تعاون الفريق المحدود: يقدم Swagger UI توثيق واجهة برمجة التطبيقات كملفات HTML ثابتة، مما يحد من التعاون على مستوى الفريق والتعاون في الوقت الحقيقي. يظل Swagger UI محدودًا عندما يحتاج العديد من المطورين والمعنيين إلى تحرير وتعليق في نفس الوقت، وإدارة الإصدارات وحل النزاعات في تصميم واجهة برمجة التطبيقات وإدارة التغيير.
  3. تكامل وقابلية التوسع المحدودة: من المفترض أن يُستخدم Swagger UI بمفرده، ولكنه يواجه قيودًا في التكامل السلس وقابلية التوسع مع أدوات إدارة واجهات برمجة التطبيقات الأخرى وعمليات تطوير البرمجيات. في إدارة واجهات برمجة التطبيقات، قد يكون من الضروري الربط مع أدوات وخدمات متنوعة، مثل الربط بمستودعات الشيفرة المصدرية، والربط مع أدوات CI/CD، ودمج بوابات واجهات برمجة التطبيقات وأدوات المراقبة.

على الرغم من القيود المذكورة أعلاه، يعتبر Swagger UI أداة مفيدة للمطورين والمستخدمين لتوثيق واختبار واجهات برمجة التطبيقات. ومع ذلك، يجب دمجه مع أدوات وخدمات أخرى تكمل Swagger UI لتغطية احتياجات إدارة واجهات برمجة التطبيقات بشكل عام.

هنا نقدم لك Apidog، أداة إدارة واجهات برمجة التطبيقات الأكثر قوة. كما هو الحال مع Swagger UI، يمكنك بسهولة تصميم واجهات برمجة التطبيقات وإنشاء مواصفات نظيفة، بالإضافة إلى اختبار واجهات برمجة التطبيقات، ومحاكاة واجهات برمجة التطبيقات، وCI/CD، والتحكم في الإصدارات، والمزيد. كما أنه يدمج إدارة دورة حياة واجهة برمجة التطبيقات ووظائف التعاون بين الفرق، مما يجعله أداة أكثر قوة واكتمالًا من Swagger UI.

API management tool

تطور Swagger UI

تم إصدار OpenAPI 3.0 في يوليو 2017، مع تحديثات وتحسينات كبيرة على Swagger 2.0. يوفر أمانًا أفضل، والتحقق من نوع البيانات بشكل أكثر صرامة، وتعريف هيكل بيانات أكثر مرونة، مما يجعله خيارًا أفضل لمواصفات واجهة برمجة التطبيقات، خاصة للتطبيقات واسعة النطاق وأنظمة المؤسسات.

كيفية استخدام Swagger لاختبار واجهة برمجة التطبيقات؟

لا يُعتبر استخدام Swagger تحديًا للمطورين، إذا كنت مبتدئًا جديدًا، إليك مثال على استخدام Swagger UI لتوثيق واختبار واجهة برمجة التطبيقات:

Swagger UI
  1. إنشاء ملف مواصفات OpenAPI بتنسيق YAML يصف نقاط نهاية واجهة برمجة التطبيقات والعمليات الخاصة بك. إذا لم تستخدم Swagger لتوثيق واجهة برمجة التطبيقات من قبل، انظر إلى دليل إنشاء توثيق API من Swagger. على سبيل المثال:
yamlCopy codeopenapi: 3.0.0
info:
  title: مثال واجهة برمجة التطبيقات
  description: واجهة برمجة تطبيقات مثال لأغراض العرض
  version: 1.0.0
servers:
  - url: http://localhost:8080
paths:
  /users:
    get:
      summary: الحصول على قائمة بالمستخدمين
      description: استرداد قائمة بجميع المستخدمين
      responses:
        '200':
          description: قائمة بالمستخدمين
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    email:
                      type: string
                      format: email

2. تنزيل وإضافة مكتبة Swagger UI إلى مشروعك. يمكنك تنزيلها من مستودع Swagger UI الرسمي على GitHub أو استخدام مدير الحزم مثل npm لتثبيتها.

3. تكوين Swagger UI عن طريق إنشاء ملف HTML يشير إلى مكتبة Swagger UI وملف مواصفات OpenAPI الخاص بك. على سبيل المثال:

htmlCopy code<!DOCTYPE html>
<html>
<head>
  <title>توثيق واجهة برمجة التطبيقات المثال</title>
  <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css">
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "http://localhost:8080/api-docs",
        dom_id: "#swagger-ui",
        presets: [SwaggerUIBundle.presets.apis],
        layout: "BaseLayout"
      })
    }
  </script>
</head>
<body>
  <div id="swagger-ui"></div>
</body>
</html>

في هذا المثال، تشير خاصية url في كائن تكوين SwaggerUIBundle إلى موقع ملف مواصفات OpenAPI الخاص بك.

ابدأ تطبيق واجهة برمجة التطبيقات الخاصة بك وافتح ملف HTML الخاص بـ Swagger UI في متصفح الويب. يجب أن ترى واجهة سهلة الاستخدام تعرض توثيق واجهة برمجة التطبيقات الخاصة بك وتسمح لك باختبار نقاط نهاية واجهة برمجة التطبيقات.

يعتبر Swagger UI أداة أساسية لتبسيط توثيق واختبار واجهات برمجة التطبيقات، مما يجعلها أكثر سهولة وملائمة. ومع ذلك، بينما يوفر Swagger UI وظيفة توليد المواصفات الأساسية واختبار نقاط النهاية، قد لا يكون كافيًا لاحتياجات الاختبار الأكثر تطورًا مثل اختبار السيناريو، والتكامل المستمر، والتوصيل (CI/CD)، واختبار الأداء.

للحصول على هذه الميزات المتقدمة، نوصي بالاستفادة من منصة إدارة واجهات برمجة التطبيقات الأكثر شمولاً مثل Apidog. يوفر Apidog مجموعة قوية من الأدوات التي تمكنك من بناء وتقديم واجهات برمجة التطبيقات عالية الجودة بشكل أكثر كفاءة وفعالية، مما يحسن الإنتاجية العامة ويعجل بنجاح المشروع.

زر

أسئلة شائعة حول Swagger UI

ما هو الفرق بين Swagger وSwagger UI؟

Swagger و Swagger UI هما أداتان مرتبطتان ولكن مختلفتان.

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

هل Swagger UI مجاني؟

نعم، Swagger UI هو برنامج مجاني ومفتوح المصدر تم إصداره بموجب ترخيص Apache 2.0. وهذا يعني أنه يمكن استخدامه وتعديله وتوزيعه بحرية، حتى لأغراض تجارية.

ما هو استخدام Swagger UI؟

يتم استخدام Swagger UI لاختبار وتوثيق وتصوير واجهات برمجة التطبيقات RESTful في واجهة بديهية وسهلة الاستخدام. إنها تبسط عملية التطوير، وتزيد من الكفاءة، وتعزز تجربة المستخدم عند استهلاك واجهات برمجة التطبيقات. من خلال تقديم توثيق مفصل وتمثيل مباشر لاستجابات واجهة برمجة التطبيقات، يعد Swagger UI أداة قيمة للمطورين والمهندسين وكُتّاب التقنية.

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

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

دليل Swagger: ما هو واجهة Swagger وكيفية استخدام Swagger