DEV Community

Cover image for كيفية مزامنة مواصفات OpenAPI مع GitHub بطريقتين
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية مزامنة مواصفات OpenAPI مع GitHub بطريقتين

إذا كان مستند OpenAPI الخاص بك موجودًا في مستودع Git، لكنك تعدّله داخل عميل API، فالمشكلة مألوفة: تنسخ YAML، تلصقه مرة أخرى، تتمنى ألا يكون أحد عدّل الملف، ثم تكتشف لاحقًا أن الاستيراد أو التصدير أسقط حقلًا أو غيّر التنسيق. الحل العملي هو جعل المستودع مصدر الحقيقة، ومزامنة التحرير مباشرة معه بدل إدارة نسختين من نفس المواصفة.

جرّب Apidog اليوم

في هذا الدليل ستتعلم كيف تزامن مواصفات OpenAPI مع GitHub باستخدام وضع Spec-First في Apidog. سنربط مزود Git، نفتح مشروعًا من مستودع وفرع، نعدّل ملف YAML، ثم ندفع التغيير إلى GitHub من داخل Apidog. نفس التدفق يعمل أيضًا مع GitLab، ويدعم Azure DevOps عبر اتصال Git.

ماذا تعني المزامنة ثنائية الاتجاه عمليًا؟

المزامنة ثنائية الاتجاه تعني أن ملف OpenAPI يتحرك في الاتجاهين بدون خطوة تصدير/استيراد يدوية:

  • من Apidog إلى Git: تعدّل المواصفة داخل Apidog، ثم تنفّذ Commit & Push ليصل التغيير إلى الفرع المحدد في المستودع.
  • من Git إلى Apidog: إذا دفع أحد أعضاء الفريق تعديلًا إلى نفس الفرع، يسحب Apidog التغيير ويحدّث المحرر.

بهذا يبقى المستودع هو مصدر الحقيقة الوحيد، بينما يعمل Apidog كمحرر غني فوق ملف OpenAPI نفسه. هذا هو جوهر سير عمل API الأصلي لـ Git: المواصفات تُراجع وتُؤرشف وتُدار مثل أي ملف آخر في قاعدة الكود.

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

قبل البدء، تأكد من توفر التالي:

  • حساب Apidog وتسجيل الدخول من تطبيق سطح المكتب أو الويب.
  • مستودع GitHub أو GitLab يحتوي على ملف OpenAPI، مثل:
    • openapi.yaml
    • openapi.yml
    • docs/openapi.yaml
  • صلاحية كتابة على الفرع الذي ستزامن معه.
  • تفعيل وضع Spec-First (Beta) في Apidog.

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

الخطوة 1: ربط مزود Git

ابدأ بتخويل Apidog للوصول إلى مزود Git الخاص بك.

  1. افتح Apidog.
  2. أنشئ مشروعًا جديدًا.
  3. اختر وضع Spec-First.
  4. عند اختيار المصدر، حدد:
    • GitHub
    • أو GitLab
  5. اضغط Authorize.
  6. سيُفتح متصفحك على شاشة OAuth الخاصة بالمزود.
  7. امنح Apidog صلاحية الوصول إلى المستودعات المطلوبة.

على GitHub، يمكنك تقييد الوصول لمستودعات محددة بدل منح الوصول لكل الحساب.

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

للمرجع الكامل، بما في ذلك Azure DevOps عبر اتصال Git، راجع وثائق وضع Spec-First.

الخطوة 2: إنشاء مشروع من مستودع وفرع

بعد ربط GitHub أو GitLab، اربط المشروع بملف OpenAPI الفعلي.

  1. اختر المستودع الذي يحتوي على المواصفة.
  2. اختر الفرع الذي تريد المزامنة معه، مثل:
    • main
    • develop
    • feature/openapi-update
  3. حدد مسار ملف OpenAPI إذا طلب Apidog ذلك، مثل: 
openapi.yaml
Enter fullscreen mode Exit fullscreen mode

أو:

docs/openapi.yaml
Enter fullscreen mode Exit fullscreen mode
  1. أنشئ المشروع.

سيقرأ Apidog الملف من الفرع المحدد ويفتحه داخل المحرر. في الشريط الجانبي، ستظهر المسارات والمخططات لأن Apidog يحلل ملف OpenAPI ويحوّله إلى بنية قابلة للتصفح.

الخطوة 3: تعديل ملف OpenAPI YAML

في وضع Spec-First، تعدّل ملف OpenAPI الخام مباشرة داخل محرر شبيه بـ IDE. تحصل على:

  • تمييز صياغة YAML.
  • تحقق مضمّن من الأخطاء.
  • إكمال تلقائي.
  • تحديث فوري للشجرة المرئية للمسارات والمخططات.

لنضف endpoint بسيطًا لفحص حالة الخدمة:

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
Enter fullscreen mode Exit fullscreen mode

أثناء الكتابة، راقب نقطتين:

  1. تظهر عملية /health في الشريط الجانبي عند تحليل المواصفة.
  2. إذا كان هناك خطأ مثل مسافة بادئة غير صحيحة، أو responses مفقودة، أو $ref غير صالح، سيشير المحرر إلى المشكلة قبل الالتزام.

مثال على خطأ شائع في YAML:

paths:
  /health:
  get:
    summary: Service health check
Enter fullscreen mode Exit fullscreen mode

في المثال السابق، get ليست متداخلة بشكل صحيح تحت /health. الصيغة الصحيحة:

paths:
  /health:
    get:
      summary: Service health check
Enter fullscreen mode Exit fullscreen mode

إذا كنت تريد فهمًا أعمق لكيفية استخدام Git مع فروقات وتاريخ مواصفات OpenAPI، راجع دليل التحكم في إصدار OpenAPI باستخدام Git.

الخطوة 4: الالتزام والدفع إلى GitHub

بعد الانتهاء من التعديل، ادفع التغيير إلى المستودع.

  1. افتح لوحة Git أو Source Control داخل المشروع.
  2. راجع التغييرات المعروضة.
  3. اكتب رسالة التزام واضحة، مثل: 
Add /health endpoint
Enter fullscreen mode Exit fullscreen mode
  1. اضغط Commit & Push.

سينشئ Apidog التزامًا على الفرع الذي اخترته، ثم يدفعه إلى المستودع البعيد. افتح GitHub وستجد الالتزام في سجل الفرع، ويؤثر على ملف OpenAPI المحدد.

إذا غيّرت رأيك قبل الدفع، يمكنك تجاهل التعديلات غير المدفوعة وإعادة الملف إلى آخر حالة مزامنة. طالما لم تضغط Commit & Push، تبقى التعديلات محلية.

الخطوة 5: التحقق من حالة المزامنة

يعرض Apidog مؤشرًا لحالة المزامنة حتى تعرف هل المحرر والفرع البعيد متطابقان أم لا.

بعد الدفع الناجح، سترى حالة مثل:

Synced just now
Enter fullscreen mode Exit fullscreen mode

هذا يعني أن ملف OpenAPI في Apidog يطابق الملف الموجود في الفرع البعيد.

مع مرور الوقت قد تظهر حالة مثل:

Synced 5 minutes ago
Enter fullscreen mode Exit fullscreen mode

وإذا دفع شخص آخر تعديلًا إلى نفس الفرع، يسحب Apidog التغيير ويحدّث المؤشر بعد المزامنة.

إذا ظهرت حالة معلقة أو قديمة، فهذا يعني أن النسخة المحلية والبعيدة تباعدتا. في هذه الحالة:

  1. اسحب آخر التغييرات.
  2. راجع الفروقات.
  3. حل أي تعارضات.
  4. أعد تنفيذ الالتزام والدفع.

استكشاف الأخطاء وإصلاحها

1. فشل الدفع بسبب الأذونات

قد يحدث ذلك إذا انتهت صلاحية التخويل أو أُلغي من GitHub/GitLab.

الحل:

  • أعد تنفيذ خطوة Authorize.
  • تأكد أن Apidog لديه صلاحية الوصول إلى المستودع.
  • تأكد أن لديك صلاحية كتابة على الفرع.

2. الفرع محمي

إذا كان الفرع main محميًا ويتطلب Pull Request، قد يتم رفض الدفع المباشر.

الحلول الممكنة:

  • زامن مع فرع آخر مثل: 
feature/update-openapi
Enter fullscreen mode Exit fullscreen mode
  • أو عدّل قواعد حماية الفرع إذا كان ذلك مناسبًا لسياسة الفريق.
  • أو استخدم Pull Request بعد دفع التغيير إلى فرع منفصل.

3. تعارضات الدمج

إذا عدّل زميلك نفس الجزء من ملف OpenAPI أثناء عملك، قد تظهر تعارضات Git.

تعامل معها مثل أي ملف نصي:

  1. اسحب آخر نسخة.
  2. افتح ملف YAML.
  3. راجع المقاطع المتعارضة.
  4. اختر الصيغة الصحيحة.
  5. تأكد أن YAML صالح.
  6. نفّذ Commit & Push مرة أخرى.

4. أخطاء التحقق داخل YAML

قد يسمح لك سير العمل بالالتزام، لكن من الأفضل إصلاح الأخطاء قبل الدفع حتى لا تكسر الوثائق أو الاختبارات أو mock servers المعتمدة على المواصفة.

أخطاء شائعة يجب مراجعتها:

  • مسافات بادئة غير صحيحة.
  • operationId مكرر.
  • schema غير مكتمل.
  • $ref يشير إلى مسار غير موجود.
  • نقص قسم responses.

الأسئلة الشائعة

هل تعمل المزامنة مع GitHub فقط؟

لا. يدعم وضع Spec-First كلًا من GitHub وGitLab مباشرة، كما يدعم Azure DevOps عبر اتصال Git. التدفق نفسه يبقى ثابتًا:

connect -> edit -> commit -> push
Enter fullscreen mode Exit fullscreen mode

الاختلاف الأساسي هو شاشة التخويل الخاصة بكل مزود.

ماذا يحدث إذا عدّل زميل في الفريق المواصفة من المستودع؟

يسحب Apidog التغييرات إلى المحرر كجزء من المزامنة ثنائية الاتجاه. إذا كانت التعديلات في أجزاء مختلفة من الملف، يمكن دمجها بسلاسة. إذا كانت في نفس الجزء، ستحتاج إلى حل تعارض Git قياسي.

هل يمكنني التراجع قبل وصول التغيير إلى GitHub؟

نعم. قبل الضغط على Commit & Push، تبقى التعديلات محلية. استخدم خيار تجاهل التعديلات غير المدفوعة لإعادة المستند إلى آخر حالة مزامنة.

ما أفضل طريقة لاستخدام هذا التدفق داخل فريق؟

استخدم نفس قواعد Git التي تطبقها على الكود:

  • اجعل المستودع مصدر الحقيقة.
  • استخدم فروعًا منفصلة للتغييرات الكبيرة.
  • راجع تعديلات OpenAPI عبر Pull Requests عند الحاجة.
  • لا تدفع إلى فرع محمي مباشرة.
  • أصلح أخطاء التحقق قبل الالتزام.

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

Top comments (0)