طريقة ربط Apidog مع GitHub و GitLab

إذا كانت مواصفات واجهة برمجة التطبيقات (API specs) الخاصة بك موجودة في Apidog ولكن مصدر الحقيقة (source of truth) الخاص بك موجود في Git، فأنت تريد أن تتوافق الاثنتان. يعمل تكامل Apidog Git على سد هذه الفجوة. فهو يتيح لك ربط مستودع GitHub أو GitLab أو Azure DevOps بمشروعك، ودفع مواصفات OpenAPI الخاصة بك إلى التحكم في الإصدار (version control)، وسحب تغييرات المستودع مرة أخرى إلى Apidog. تحصل على سجل تدقيق نظيف، ومراجعة تعليمات برمجية (code-review) لتغييرات المواصفات، ونسخة احتياطية تبقى سليمة بغض النظر عما يحدث داخل التطبيق.

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

ما يفعله تكامل Apidog Git

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

القدرة الأولى هي المزامنة ثنائية الاتجاه من خلال وضع Spec-First. يمكنك تحرير مستند OpenAPI الخاص بك كـ YAML أو JSON داخل محرر Apidog الشبيه بـ IDE، وتثبيت تغييراتك (commit your changes)، ودفعها (push them) إلى الفرع المتصل. عندما يقوم شخص آخر بتحديث المواصفات في المستودع، يمكنك سحب هذه التغييرات مرة أخرى إلى Apidog. هذه رحلة ذهاب وإياب حقيقية: تتدفق التعديلات إلى Git، وتتدفق تغييرات المستودع مرة أخرى.

القدرة الثانية هي النسخ الاحتياطي التلقائي لـ Git لمواصفات API. هنا، يقوم Apidog بتصدير ملف OpenAPI/Swagger الخاص بكل وحدة ودفعه إلى مستودع وفقًا لجدول زمني. هذا أحادي الاتجاه وتلقائي. يمكنك تكوينه مرة واحدة، ويحتفظ النظام بنسخة مؤرشفة من مواصفاتك في Git دون الحاجة إلى بذل أي جهد. إنها شبكة أمان، وليست سير عمل تحريري.

ضع هذا التمييز في الاعتبار لبقية المقال. عندما نقول "مزامنة"، فإننا نعني تدفق وضع Spec-First ثنائي الاتجاه. وعندما نقول "نسخ احتياطي"، فإننا نعني التصدير المجدول أحادي الاتجاه.

مزودو Git المدعومون

يدعم Apidog المزودين الثلاثة الأكثر استخدامًا بالفعل من قبل معظم الفرق. يتصل GitHub و GitLab مباشرة من خلال تدفقات التفويض الأصلية الخاصة بهما. يتصل Azure DevOps من خلال اتصال Git عام، والذي يعمل مع أي مضيف Git يدعم مصادقة HTTPS القياسية.

اتصال Git العام هو مخرج الطوارئ. إذا لم يكن مضيفك GitHub أو GitLab بالاسم، ولكنه يتحدث Git القياسي عبر HTTPS مع مصادقة الرمز، فإن الاتصال العام يتعامل معه عادةً. Azure DevOps هو الحالة البارزة، لكن المسار نفسه يغطي الإعدادات المستضافة ذاتيًا التي تعرض عنوان URL لنسخ HTTPS.

ربط مزود Git الخاص بك

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

بالنسبة لـ GitHub، يمكنك التفويض من خلال شاشة OAuth الخاصة بـ GitHub. يطلب Apidog الوصول إلى المستودع حتى يتمكن من قراءة المواصفات ودفع التثبيتات. إذا كان المستودع ينتمي إلى مؤسسة، فقد يوجه GitHub الطلب من خلال مسؤول مؤسسة يوافق على الوصول من طرف ثالث. يتم تفويض المستودعات الشخصية على الفور تحت حسابك الخاص.

بالنسبة لـ GitLab، يطابق التدفق GitHub. تسجل الدخول من خلال شاشة OAuth الخاصة بـ GitLab وتمنح الوصول إلى المستودع. يعمل GitLab المُدار ذاتيًا طالما أن Apidog يمكنه الوصول إلى المثيل عبر الشبكة.

بالنسبة لـ Azure DevOps، يمكنك استخدام اتصال Git العام. بدلاً من مصافحة OAuth، توفر عنوان URL لاستنساخ HTTPS للمستودع ورمز وصول شخصي (PAT). قم بإنشاء PAT في Azure DevOps بإذن لقراءة وكتابة التعليمات البرمجية، ثم الصقه في Apidog. الرمز هو بيانات الاعتماد التي تسمح لـ Apidog بدفع التثبيتات، لذا قم بتحديد نطاقه للمستودعات التي يحتاجها بالضبط.

بعض ملاحظات الأذونات التي توفر الوقت:

• مستودعات المؤسسة مقابل المستودعات الشخصية. تتطلب مستودعات المؤسسة غالبًا موافقة مسؤول على التكامل مرة واحدة. إذا بدا أن تفويضك ناجح ولكن Apidog لا يمكنه رؤية المستودع، فعادة ما يكون هناك موافقة مفقودة من المسؤول.
• تحديد نطاق الرمز بإحكام. لـ Azure DevOps وأي اتصال عام، امنح PAT إذن القراءة/الكتابة على التعليمات البرمجية للمشروع المستهدف فقط. تجنب رموز الوصول الكامل للحساب.
• المستودعات الخاصة جيدة. يعمل Apidog مع المستودعات الخاصة. يأتي الوصول من التفويض أو الرمز الذي تقدمه، وليس من الرؤية العامة.

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

مزامنة ثنائية الاتجاه مع وضع Spec-First

وضع Spec-First هو المكان الذي توجد فيه المزامنة ثنائية الاتجاه. إنه يحول Apidog إلى محرر مواصفات يقوم بالتثبيت في Git مثل أي تعليمات برمجية أخرى. يمكنك قراءة المرجع الكامل في وثائق Apidog الرسمية؛ وإليك كيفية عمل الرحلة ذهابًا وإيابًا في الممارسة العملية.

تقوم بتحرير مستند OpenAPI مباشرةً كـ YAML أو JSON. المحرر من نوع IDE: يمنحك تمييز بناء الجملة، والتحقق المباشر، والإكمال التلقائي، بحيث تظهر مرجع $ref غير صحيح أو حقل مطلوب مفقود أثناء الكتابة بدلاً من بعد الدفع. أثناء التحرير، يقوم الشريط الجانبي الأيسر بتحليل المستند تلقائيًا إلى مخطط تفصيلي ومسارات وعمليات ومخططات، بحيث يمكنك التنقل في مواصفات كبيرة دون التمرير عبر النص الخام.

يبدو التعديل النموذجي كالتالي. لنفترض أنك أضفت نقطة نهاية:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

عند حفظ هذا التغيير، يقوم Apidog بوضعه كتحرير محلي. ثم تقوم بالتثبيت برسالة والدفع إلى الفرع المتصل، تمامًا كما تفعل مع أي سير عمل Git. بعد نجاح الدفع، يشير مؤشر المزامنة إلى "تمت المزامنة للتو" لتأكيد أن Apidog والفرع يحتويان على نفس المحتوى.

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

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

هذه الوتيرة من التثبيت والدفع هي جوهر سير عمل API الأصيل في Git، حيث تخضع تغييرات المواصفات لنفس آليات المراجعة والتاريخ والتراجع مثل بقية قاعدة التعليمات البرمجية الخاصة بك. يعلق المراجعون على فرق YAML في طلب السحب، وتوافقات البوابة تدمج التغييرات، ويقرأ تاريخ تصميم API الخاص بك مثل تاريخ التعليمات البرمجية الخاصة بك.

النسخ الاحتياطي التلقائي لمواصفات API في Git

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

هذه هي الآلية. يمكن لـ Apidog إجراء نسخ احتياطي لملف OpenAPI/Swagger لكل وحدة إلى مستودع Git، حيث يتم دعم GitHub و GitLab و Azure DevOps جميعًا. بمجرد حفظ تكوين النسخ الاحتياطي، يقوم النظام تلقائيًا بدفع ملف OpenAPI Spec الخاص بالوحدة إلى المستودع المحدد. يتم الدفع خلال نافذة عشوائية خارج أوقات الذروة ليلًا، مما يبقيه بعيدًا عن ساعات عملك ويوزع الحمل.

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

تدفق النسخ الاحتياطي أحادي الاتجاه حسب التصميم. يكتب Apidog إلى المستودع؛ ولا يقرأ التغييرات منه. إذا كنت تريد تدفق تعديلات المستودع إلى Apidog، فهذه هي وظيفة وضع Spec-First، وليست النسخ الاحتياطي. استخدم النسخ الاحتياطي عندما يكون هدفك هو المتانة والتاريخ دون تغيير طريقة عمل فريقك اليومية.

اختيار فرع وبنية المستودع

تُشكل القرارات الهيكلية التي تتخذها مقدمًا مدى سلاسة التكامل لاحقًا. يهيمن سؤالان: أي فرع، وكم عدد المستودعات.

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

مستودع واحد أم عدة مستودعات. لا توجد إجابة صحيحة واحدة، لكن المفاضلات واضحة:

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

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

أذونات الفريق والوصول

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

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

داخل مزود Git الخاص بك، تهم بيانات الاعتماد. بالنسبة لـ GitHub و GitLab، يحمل تفويض OAuth وصول المستخدم الذي منحه. بالنسبة لـ Azure DevOps والاتصالات العامة، يعد رمز الوصول الشخصي (PAT) هو بيانات الاعتماد، تعامل معه كسر. لا تلصق الرموز المميزة في المستندات المشتركة، قم بتحديد نطاقها للمستودعات المستهدفة فقط، وقم بتدويرها بنفس وتيرة تدوير الأسرار الأخرى. إذا غادر شخص ما الفريق، قم بإلغاء رمز الوصول الخاص به وأعد التفويض تحت حساب لا يزال نشطًا.

المبدأ بسيط: التكامل محكم الإغلاق بقدر ما هو أضعف رمز خلفه. حافظ على نطاقات ضيقة وملكيه واضحة.

التعامل مع تعارضات الدمج والانحراف

نظرًا لأن Apidog يلتزم بسجل Git حقيقي، فإنه يرث نموذج تعارض Git، وأدوات Git لحلها. تحدث التعارضات عندما يقوم شخصان بتغيير نفس الجزء من المواصفات قبل المزامنة.

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

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

الانحراف، حيث يتباعد Apidog والمستودع بهدوء، هو النسخة البطيئة من نفس المشكلة. مؤشر "تمت المزامنة للتو" هو تحذيرك المبكر. إذا لم يظهر "تمت المزامنة"، فهناك شيء غير مدفوع أو غير مسحوب. تعامل مع ذلك كإشارة للتوفيق قبل أن تتسع الفجوة.

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

تعود معظم مشكلات التكامل إلى المصادقة، أو اختيار الفرع، أو المزامنة المتقطعة. راجع الجدول قبل افتراض أن هناك خطأ أعمق.

إذا كانت المصادقة هي الموضوع المتكرر، وهي كذلك عادةً، فابدأ بالتأكد من أن بيانات الاعتماد نشطة ومحددة النطاق بشكل صحيح. رمز الوصول الملغى أو موافقة المؤسسة المفقودة تفسر غالبية تقارير "لقد توقف عن العمل للتو".

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

هل المزامنة أحادية الاتجاه أم ثنائية الاتجاه؟

يعتمد ذلك على القدرة التي تستخدمها. وضع Spec-First ثنائي الاتجاه: تقوم بدفع التعديلات إلى Git وسحب تغييرات المستودع مرة أخرى إلى Apidog. النسخ الاحتياطي التلقائي أحادي الاتجاه: يقوم Apidog بتصدير مواصفات كل وحدة إلى المستودع وفقًا لجدول زمني ولا يقرأ التغييرات مرة أخرى.

أين يتم تخزين مواصفاتي؟

في مستودع Git الذي تربطه. بالنسبة لوضع Spec-First، يعيش مستند OpenAPI الخاص بك على الفرع الذي تدفع إليه. بالنسبة للنسخ الاحتياطي التلقائي، يتم تثبيت ملف OpenAPI/Swagger المُصدّر لكل وحدة في المستودع الذي قمت بتكوينه. في كلتا الحالتين، يحتفظ Git بالنسخة الإصدارية، وتحتفظ بالتحكم الكامل في المستودع.

إلى أي فرع يجب أن أقوم بالمزامنة؟

استخدم main للمواصفات الأساسية واستخدم فروعًا خاصة للتغييرات قيد التقدم. تسمح المزامنة مع فرع خاص بتمرير تغيير المواصفات عبر طلب سحب ومراجعة قبل دمجه، مما يعكس كيف تتحرك التعليمات البرمجية الخاصة بك بالفعل عبر Git.

ماذا يحدث إذا تم إلغاء رمز الوصول الخاص بي؟

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

الخلاصة

يمنحك تكامل Apidog Git أداتين متكاملتين: المزامنة ثنائية الاتجاه من خلال وضع Spec-First للفرق التي تتعامل مع المواصفات كتعليمات برمجية، والنسخ الاحتياطي التلقائي لكل وحدة لأي شخص يريد فقط شبكة أمان مؤرشفة. يعمل كلاهما عبر GitHub و GitLab و Azure DevOps، لذلك يمكنك ربط المزود الذي تستخدمه بالفعل بدلاً من اعتماد مزود جديد.

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