التعاون المتكامل مع Git لاختبار وهندسة واجهات برمجة التطبيقات

تُعد مواصفات OpenAPI الخاصة بك بمثابة العقد بين واجهة برمجة التطبيقات (API) ومستهلكيها. ولكن أين يقيم هذا العقد؟

في كثير من الأحيان، توجد مواصفات API في أدوات معزولة - يتم تصديرها مرة واحدة، ثم تُنسى، ونادرًا ما يتم تحديثها عند تغير التنفيذ. تختلف الوثائق. تتشعب مجموعات الاختبار. يوافق المراجعون على تغييرات الكود دون رؤية تحديثات المواصفات المقابلة.

وضع المواصفات أولاً (Spec-first Mode) يقلب هذا النموذج. تصبح ملفات OpenAPI أو Swagger الخاصة بك هي مصدر الحقيقة، ويتم تخزينها مباشرة في مستودع Git الخاص بك جنبًا إلى جنب مع كود التنفيذ. يتدفق كل تغيير في المواصفات عبر نفس الفروع وطلبات السحب وعملية المراجعة التي تستخدمها بالفعل. تصميم واجهة برمجة التطبيقات (API)، اختبارها، وتوثيقها تظل كلها متزامنة - تلقائيًا.

في هذا البرنامج التعليمي، سأرشدك خلال إعداد مشروع بوضع المواصفات أولاً (Spec-first) في Apidog، وتحرير المواصفات مع فريقك، والحفاظ على كل شيء متزامنًا مع سير عمل Git الخاص بك.

ما هو وضع المواصفات أولاً (Spec-first Mode)؟

في مشروع واجهة برمجة تطبيقات نموذجي، تقوم بإنشاء نقاط نهاية من خلال نماذج مرئية أو استيراد مواصفات موجودة كنقطة بداية. تخزن الأداة تعريفات واجهة برمجة التطبيقات داخليًا، ويكون تكامل Git (إذا كان متاحًا) خطوة تصدير.

وضع المواصفات أولاً (Spec-first Mode) مختلف. مساحة العمل الأساسية تعتمد على الملفات:

• `openapi.yaml` أو `openapi.json` موجودة في مستودعك
• يقوم Apidog بتحليل هذه الملفات وإنشاء هيكل API قابل للتصفح
• تقوم بتحرير الملفات مباشرة (أو من خلال النماذج المدعومة)
• تتم مزامنة التغييرات تلقائيًا مرة أخرى مع Git

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

المتطلبات الأساسية

للمتابعة، ستحتاج إلى:

• حساب Apidog (الطبقة المجانية تعمل)
• مستودع Git مع ملف OpenAPI/Swagger، أو مستودع فارغ للبدء من جديد
• حق الوصول بالكتابة إلى المستودع
• إلمام أساسي بـ بناء جملة OpenAPI أو Swagger

الخطوة 1: إنشاء مشروع بوضع المواصفات أولاً (Spec-first Project)

انقر على + مشروع جديد في Apidog واختر وضع المواصفات أولاً (Spec-first Mode) كنوع للمشروع.

بعد ذلك، قم بتوصيل مزود Git الخاص بك:

1. اختر مزودك (GitHub، GitLab، Azure DevOps، أو Bitbucket)
2. اختر منظمة أو مساحة عمل
3. اختر مستودعًا موجودًا أو أنشئ واحدًا جديدًا
4. اختر الفرع الرئيسي للمزامنة

سيقوم Apidog بالمزامنة مع الفرع الافتراضي لمستودعك. إذا لم يكن اسمه `main`، يتكيف Apidog تلقائيًا.

الخطوة 2: تهيئة مزامنة الويب هوك (موصى بها)

أثناء الإعداد، سترى خيارًا لتثبيت webhook. هذا يمكن المزامنة التلقائية كلما قام فريقك بالدفع إلى المستودع.

ملاحظة: يتطلب تثبيت الويب هوك عادةً إذن المسؤول على المستودع. إذا لم يكن لديك حق الوصول كمسؤول، فتخط هذه الخطوة - لا يزال بإمكانك المزامنة يدويًا باستخدام Git Pull.

فوائد الويب هوك:

• يقوم الفريق بدفع التغييرات ← يتزامن Apidog تلقائيًا
• لا حاجة للتحديث اليدوي
• الجميع يرى أحدث حالة للمواصفات

إذا تخطيت إعداد الويب هوك في البداية، يمكنك إضافته لاحقًا من إعدادات المشروع > Git والفروع.

الخطوة 3: استكشاف مساحة عمل المواصفات

بعد الإنشاء، يفتح مشروعك مساحة عمل المواصفات - المركز الرئيسي للتحرير القائم على الملفات وعمليات Git.

ثلاث لوحات تعمل معًا:

انقر على نقطة نهاية في شجرة الهيكل ← يبرز Apidog القسم المقابل في ملف المصدر الخاص بك. تنقل من عرض API عالي المستوى إلى YAML منخفض المستوى دون التبديل بين علامات التبويب.

الخطوة 4: تحرير ملفات المواصفات الخاصة بك

عرض الكود: التحرير المباشر

بالنسبة لمعظم الملفات - YAML، JSON، Markdown - استخدم عرض الكود لتحرير النص الخام.

تبقى تعديلاتك في الملف. لا يقوم Apidog بتحويلها أو تخزينها بشكل منفصل. يظل ملف المواصفات هو المصدر الوحيد للحقيقة.

عرض النموذج: التحرير المنظم

بالنسبة لعقد OpenAPI المدعومة - نقاط النهاية، المخططات، التعريفات، ونظرة عامة على API - قم بالتبديل إلى عرض النموذج.

عرض النموذج مفيد عندما:

• إضافة نقاط نهاية مع جميع الحقول المطلوبة دون حفظ هيكل YAML
• تحرير المخططات بصريًا
• تحديث تعريفات الأمان وبيانات تعريف API

إذا كانت العقدة لا تدعم التحرير في النموذج، يبقيك Apidog في عرض الكود.

الخطوة 5: التحقق والمعاينة الفورية

يتضمن وضع المواصفات أولاً (Spec-first Mode) التحقق في الوقت الفعلي ومعاينة الوثائق - لا توجد أدوات خارجية مطلوبة.

التحقق من المشكلات باستخدام التحقق

انقر على التحقق في رأس المحرر. تعرض اللوحة جميع التحذيرات والأخطاء في مواصفاتك الحالية.

تعرض الشارة العدد الإجمالي للمشكلات. تحقق من:

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

أصلح المشكلات قبل الالتزام. لن يحتاج مراجعو فريقك إلى اكتشافها يدويًا.

معاينة وثائقك

انقر على معاينة لترى كيف تظهر مواصفاتك كوثائق لـ API.

بالنسبة لنقاط النهاية، تتضمن المعاينة علامتي تبويب:

بالنسبة للمخططات والتعريفات، تعرض المعاينة عرض الوثائق المقدمة.

يتشارك التحقق والمعاينة نفس اللوحة الجانبية. يغلق فتح أحدهما الآخر تلقائيًا.

الخطوة 6: سحب التحديثات من فريقك

عندما يقوم المتعاونون بدفع التغييرات إلى مستودعك، قم بإحضارها إلى Apidog:

1. افتح مساحة عمل المواصفات
2. انقر على اسم الفرع الحالي في الشريط الجانبي
3. اختر Git Pull

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

الخطوة 7: الالتزام ودفع تغييراتك

بعد تحرير الملفات في Apidog، أرسل تحديثاتك مرة أخرى إلى Git:

1. قم بإجراء التغييرات في مساحة عمل المواصفات
2. انقر على التغييرات في الشريط الجانبي لرؤية الملفات المعدلة، المضافة، المعاد تسميتها، والمحذوفة
3. انقر على Commit & Push (التزام ودفع)
4. اختر الملفات المراد تضمينها
5. اكتب رسالة الالتزام
6. انقر على Push (دفع)

تظهر تحديثات مواصفاتك الآن في نفس سير عمل طلب السحب مثل تغييرات الكود الخاص بك. يمكن لزملائك في الفريق المراجعة، التعليق، والموافقة - كل من التنفيذ وعقد API في مكان واحد.

نصيحة: استخدم تجاهل جميع التغييرات إذا كنت ترغب في التخلي عن التعديلات المحلية قبل الدفع.

الخطوة 8: العمل مع الفروع

يدعم وضع المواصفات أولاً (Spec-first Mode) التعاون الكامل القائم على الفروع. يقوم Apidog بربط فروع Git بفروع المشروع، مما يتيح لك التبديل بين إصدارات المواصفات.

عمليات الفروع الشائعة

تعمل إدارة الفروع بالطريقة نفسها التي تتوقعها من Git - فروع الميزات، الإصدارات، والتطوير المتوازي كلها تتزامن بشكل صحيح.

الخطوة 9: التكامل مع CI/CD

بما أن مواصفاتك موجودة في Git، فإنها تتناسب بشكل طبيعي مع خطوط أنابيب الأتمتة:

• تدقيق المواصفات في كل طلب سحب (PR) باستخدام التحقق من Apidog أو أدوات مثل Spectral
• إنشاء الوثائق تلقائيًا عند دمج المواصفات مع الفرع الرئيسي
• تشغيل اختبارات API التي يتم تشغيلها بواسطة تغييرات المواصفات
• المزامنة مع الأنظمة النهائية - بوابات API، خوادم وهمية، مولدات SDK

مثال لسير عمل GitHub Actions:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

تخضع مواصفات واجهة برمجة التطبيقات الخاصة بك الآن لنفس بوابات الجودة مثل كود تطبيقك.

بديل: المشاريع المدعومة بالتخزين

إذا لم تكن مستعدًا لتوصيل مستودع Git خارجي، يوفر Apidog مشاريع Spec-first مدعومة بالتخزين.

تستخدم هذه المشاريع تخزين Apidog الداخلي ولكنها لا تزال توفر:

• التحرير القائم على الملفات
• التحقق والمعاينة
• إدارة الفروع

تتعدل تسميات واجهة المستخدم قليلاً:

• يصبح Git Pull مزامنة (Sync)
• يصبح Commit & Push (التزام ودفع) حفظ (Save)

قم بالترحيل إلى Git الخارجي متى كان فريقك مستعدًا.

الملخص

مع وضع المواصفات أولاً (Spec-first Mode)، يصبح سير عمل API الخاص بك:

وضع المواصفات أولاً (Spec-first Mode) يجعل ملفات OpenAPI هي العقد الذي ينبغي أن تكون عليه - ذات إصدارات، ومراجعة، ومتوافقة دائمًا مع الكود الخاص بك.

هل أنت مستعد للتجربة؟ أنشئ مشروع Spec-first في Apidog وقم بتوصيل أول مستودع لك.