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

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

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

دعنا نبدأ.

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

المزامنة ثنائية الاتجاه تعني أن التعديلات تتدفق في كلا الاتجاهين، تلقائيًا، دون أي خطوة تصدير في المنتصف.

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

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

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

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

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

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

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

أولاً، قم بتخويل Apidog للتواصل مع المزود الخاص بك.

1. افتح Apidog وأنشئ مشروعًا جديدًا، اختر وضع Spec-First.
2. عند مطالبتك باختيار مصدر، حدد مزودك، GitHub أو GitLab.
3. انقر فوق "Authorize" (تخويل). يفتح متصفحك شاشة OAuth الخاصة بالمزود.
4. امنح Apidog حق الوصول إلى المستودعات التي تريد مزامنتها. على GitHub، يمكنك تحديد هذا النطاق ليشمل مستودعات معينة بدلاً من حسابك بالكامل.

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

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

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

الآن وجه Apidog إلى المواصفات الفعلية.

1. مع ربط المزود، اختر المستودع الذي يحتوي على ملف OpenAPI الخاص بك.
2. اختر الفرع للمزامنة معه، وعادةً ما يكون main. هذا هو الفرع الذي ستستقر عليه التزاماتك والفرع الذي يراقبه Apidog للتغييرات الواردة.
3. أكد مسار مستند OpenAPI إذا طلب Apidog ذلك (على سبيل المثال openapi.yaml في جذر المستودع، أو ضمن docs/).
4. أنشئ المشروع.

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

الخطوة 3: تحرير ملف OpenAPI YAML الخاص بك في محرر الأكواد

يمنحك وضع Spec-First محررًا على غرار بيئة التطوير المتكاملة (IDE) لملف OpenAPI YAML الخام، مع تمييز بناء الجملة والتحقق المضمن والإكمال التلقائي. تكتب OpenAPI مباشرةً؛ ويحافظ Apidog على المخطط المرئي متزامنًا أثناء الكتابة.

دعنا نضيف نقطة نهاية صغيرة. لنفترض أنك تريد فحص الحالة الصحية:

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

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

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

الخطوة 4: الالتزام والدفع (Commit & Push)

عندما يبدو التعديل صحيحًا، أرسله إلى GitHub.

1. افتح لوحة الالتزام (منطقة Git/التحكم بالمصدر للمشروع).
2. راجع التغيير. يعرض Apidog ما تم تعديله مقارنة بالنسخة المزامنة.
3. اكتب رسالة التزام، تعامل معها كأي التزام: Add /health endpoint (إضافة نقطة نهاية /health).
4. انقر فوق "Commit & Push" (التزام ودفع).

يقوم Apidog بالالتزام بالفرع الذي اخترته ويدفع التغييرات إلى المستودع البعيد. افتح مستودعك على GitHub وسترى الالتزام في سجل الفرع، مؤلفًا كما هو متوقع، ويؤثر بالضبط على ملف OpenAPI.

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

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

يعرض Apidog مؤشر مزامنة لتظل دائمًا على دراية بالوضع.

بعد الدفع الناجح، يقرأ المؤشر "Synced just now." (تمت المزامنة للتو). هذا هو تأكيدك بأن المحرر والفرع البعيد يحتويان على نفس المستند. مع مرور الوقت، يتحدث المؤشر ("Synced 5 minutes ago" - تمت المزامنة قبل 5 دقائق)، وعندما يدفع شخص آخر، يسحب Apidog التغيير ويعيد تعيين المؤشر بعد التوفيق.

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

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

قليل من الأمور التي غالبًا ما تتسبب في مشاكل للمستخدمين لأول مرة.

• انتهاء صلاحية التخويل أو إلغاؤه. إذا بدأت عمليات الدفع بالفشل بسبب خطأ في الأذونات، أعد تشغيل التخويل من الخطوة 1. يمكن إلغاء صلاحية الرموز المميزة من جانب المزود أو انتهاء صلاحيتها ببساطة.
• فرع خاطئ. سيتم رفض الدفع إلى فرع main محمي يتطلب طلبات سحب (pull requests). إما أن تتم المزامنة مع فرع آخر أو تعديل قواعد حماية الفرع. تحقق جيدًا من أن الفرع المختار في الخطوة 2 يتطابق مع المكان الذي تتوقع أن تستقر فيه الالتزامات.
• تعارضات الدمج (Merge conflicts). إذا دفع زميل في الفريق إلى نفس الفرع بينما كنت تقوم بالتحرير، فقد تقدم المستودع البعيد على نسختك المحلية. اسحب أحدث التغييرات، وقم بتوفيق YAML المتداخل، ثم قم بالالتزام مرة أخرى. نظرًا لأن المواصفات هي نص عادي، يتم حل التعارضات بنفس طريقة حل أي تعارض في التعليمات البرمجية.
• أخطاء التحقق من الصحة تعرقل سير عملك. لن يمنعك Apidog من الالتزام بملف YAML غير صالح، ولكن يجب عليك إصلاح ما يشير إليه المدقق المضمن أولاً. المواصفات النظيفة تحافظ على صدق وثائقك، ومحاكياتك، واختباراتك التي تم إنشاؤها.

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

هل تعمل المزامنة مع GitHub أيضًا مع GitLab و Azure DevOps؟

نعم. يدعم وضع Spec-First كلاً من GitHub و GitLab مباشرةً، و Azure DevOps عبر اتصال Git. تدفق الربط-التحرير-الالتزام-الدفع (connect-edit-commit-push) هو نفسه عبر الأنظمة الثلاثة؛ يختلف فقط شاشة التخويل حسب المزود.

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

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

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

نعم. حتى تنقر على "Commit & Push"، تعديلاتك محلية. استخدم "discard unpushed edits" (تجاهل التعديلات غير المدفوعة) لإعادة المستند إلى آخر حالة مزامنة، ولا يصل شيء إلى المستودع البعيد.