كيفية استخدام Swagger لإنشاء واجهة برمجة تطبيقات Node.js

توفر وثائق API كعنصر حيوي في تطوير البرمجيات، مما يوفر للمستخدمين رؤى حول كيفية التفاعل مع واجهات برمجة التطبيقات وخدماتها. في هذا الدليل، نستكشف الاستفادة من Swagger، وهي أداة، لتوثيق واجهات برمجة التطبيقات المبنية باستخدام Node.js، مما يمكّن من توليد وثائق API تفاعلية تلقائيًا وتسهيل اختبار API.

بالإضافة إلى ذلك، نقدم Apidog كتكامل قوي لإدارة API محسّنة، تشمل الاختبار عبر بروتوكولات مختلفة والتعاون السلس. مع تعليمات خطوة بخطوة ورؤى، يمكن للمطورين تبسيط تطوير API وضمان القوة والكفاءة في تطبيقاتهم.

button

دليل شامل حول توثيق API في Swagger

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

إعداد بيئة Node.js

قبل أن نبدأ في إنشاء واجهة برمجة التطبيقات Node.js الخاصة بنا باستخدام Swagger، دعنا نتأكد من إعداد بيئة التطوير لدينا بشكل صحيح. تأكد من أن لديك Node.js مثبتة على جهازك. يمكنك تنزيل وتثبيت Node.js من الموقع الرسمي أو استخدام مدير حزم مثل npm أو yarn للتثبيت.

تثبيت أدوات Swagger

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

Swagger Editor: محرر ويب مصمم لتصميم واختبار مواصفات Swagger.
Swagger UI: واجهة سهلة الاستخدام لتصور والتفاعل مع وثائق Swagger.
Swagger Codegen: أداة لتوليد خوادم التجريب ومكتبات العملاء بناءً على مواصفات Swagger.

يمكنك تثبيت هذه الأدوات عالميًا باستخدام npm أو yarn:

npm install -g swagger-cli swagger-ui-express

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

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

إليك مثال أساسي لمواصفات Swagger لواجهة برمجة تطبيقات Todo بسيطة:

openapi: 3.0.0
info:
  title: Todo API
  version: 1.0.0
  description: واجهة برمجة تطبيقات Todo بسيطة
paths:
  /todos:
    get:
      summary: احصل على جميع المهام
      responses:
        '200':
          description: قائمة بالمهام
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    completed:
                      type: boolean
    post:
      summary: إنشاء مهمة جديدة
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: شراء المواد الغذائية
                completed:
                  type: boolean
                  example: false
      responses:
        '201':
          description: تم الإنشاء

في هذه المواصفات Swagger:

نحدد عنوان API، والإصدار، والوصف تحت قسم info.
نحدد نقطتي نهاية (/todos)، واحدة لاسترداد جميع المهام (GET) وأخرى لإنشاء مهمة جديدة (POST).
يتضمن كل نقطة نهاية ملخصًا، وجسم الطلب (إذا كان ذلك ممكنًا)، وأنماط الاستجابة.

اختبار واجهات برمجة التطبيقات على Swagger

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

سنستخدم واجهة وثيقة Swagger لإجراء بعض الطلبات وملاحظة النتائج.

إنشاء مستخدم:

إنشاء منشور:

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

باتباع هذه الأمثلة، يمكننا الاستمرار في اختبار طرق الطلب الأخرى مثل استخدام PUT لتحديث المستخدمين أو المنشورات، واستخدام GET لقراءة المستخدمين أو المنشورات، واستخدام DELETE لإزالتها من قاعدة البيانات.

في الختام، من الواضح أن وثائق API تلعب دورًا محوريًا في دورة حياة تطوير البرمجيات، مما يسهل التعاون ويضمن تجارب مستخدم سلسة. تشمل مزايا Swagger، من بين أمور أخرى،:

تزامن وثائق API مع كل من الخوادم والعملاء.
تيسير إنشاء وتفاعل الوثائق الخاصة بـ REST API. يتيح استخدام إطار عمل Swagger UI رؤى شاملة حول استجابات API للمعلمات.
توفير استجابات بتنسيقات JSON و XML.
المرونة للتطبيق عبر تقنيات متنوعة.

إدارة وثائق API مع Apidog

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

Apidog هي أداة اختبار API أقوى مقارنة بـ Postman. تدعم واجهات تصحيح الأخطاء لبروتوكولات مثل HTTP(s)، WebSocket، Socket، gRPC، وتتوافق مع إضافات IDEA.

button

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

تصدير Swagger إلى JSON

كما هو موضح أدناه، اختر "تحويل وحفظ كملف JSON" لتصدير وثيقة Swagger كملف JSON.

استيراد ملفات Swagger إلى Apidog

افتح Apidog، أنشئ مشروعًا، ثم انتقل إلى "إعدادات المشروع->استيراد البيانات->OpenAPI/Swagger->استيراد ملف" واستورد ملف JSON بتنسيق Swagger الذي قمت بتصديره سابقًا.

عند الاستيراد، سيكون هناك معاينة، ويمكنك اختيار استيراد الكل، أو استيراد API بشكل انتقائي. بعد نجاح الاستيراد، يمكنك اختيار بيئة لاختبار API.

تحقق من هذا الرابط لمعرفة المزيد: https://apidog.com/help/importing-and-exporting-data/importing-data/importing-openapi-specification