ما هو سير عمل API الأصلي لـ Git؟ وكيف تبني واحداً؟

يعيش الكود الخاص بك في Git. تعيش خطوط أنابيب CI والمراجعات وسجل الإصدارات الخاصة بك في Git. فلماذا تعيش مواصفات API الخاصة بك في مكان آخر؟

يحافظ سير عمل API الأصلي لـ Git على تعريف OpenAPI الخاص بك في نفس مكان الكود الخاص بك. يمكنك تحرير المواصفات كملف YAML أو JSON عادي، والالتزام بها، ودفعها من خلال نفس عملية المراجعة التي تستخدمها لكل شيء آخر. لا توجد قاعدة بيانات سحابية منفصلة. لا توجد عملية تصدير واستيراد متكررة. المواصفات مجرد ملف آخر في مستودعك.

💡

يدعم Apidog الآن هذا مباشرةً من خلال وضع Spec-First Mode. يمكنك تصميم API الخاص بك في محرر بأسلوب IDE، ثم مزامنة الملفات الخام ثنائياً مع GitHub أو GitLab. يشرح هذا الدليل ما يعنيه سير عمل API الأصلي لـ Git، ولماذا تسبب المواصفات المقيدة بالسحابة الاحتكاك، وكيفية إعداد وضع Spec-First Mode خطوة بخطوة.

زر

ماذا يعني سير عمل API الأصلي لـ Git

يعامل سير عمل API الأصلي لـ Git مواصفات API الخاصة بك ككود. يوجد ملف OpenAPI في مستودع جنبًا إلى جنب مع خدماتك. كل تغيير هو التزام (commit). كل التزام له مؤلف ورسالة وفرق (diff).

يمنحك هذا ثلاثة أشياء تتوقعها بالفعل من الكود المصدري:

سجل الإصدارات. يمكنك رؤية من قام بتغيير نقطة نهاية ومتى. يعمل git blame على مواصفاتك.
التفرع والمراجعة. تمر تغييرات المواصفات عبر طلبات السحب (pull requests). يرى المراجعون الفرق الدقيق قبل دمج أي شيء.
مصدر واحد للحقيقة. الملف في main هو العقد. الأدوات والوثائق والمحاكاة كلها تقرأ منه.

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

يخزن النهج المعاكس مواصفاتك داخل تطبيق سحابي خاص. يعمل هذا حتى يكبر فريقك أو تنضج عمليتك. ثم تظهر الشقوق.

مشكلة مواصفات API المقيدة بالسحابة

تحتفظ معظم أدوات تصميم API بالمواصفات في قاعدة بياناتها الخاصة. يمكنك التحرير من خلال واجهة المستخدم الخاصة بهم. "الملف" الذي تعتقد أنك تملكه هو في الواقع صف في نظام شخص آخر.

ينهار هذا بطرق يمكن التنبؤ بها.

تتم المراجعة في مكانين. تمر تغييرات الكود عبر GitHub. تمر تغييرات المواصفات عبر أداة منفصلة لها تعليقاتها وسجلها الخاص. يغير المراجعون السياق. تتراجع الموافقات عن المزامنة.

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

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

الأتمتة تحاربك. تريد أدوات فحص الكود (Linters) واختبارات العقود (contract tests) ومولدات الكود (code generators) ملفًا على القرص. المواصفات المقيدة بالسحابة تفرض خطوة جلب قبل تشغيل أي من ذلك.

يؤدي التعامل مع مواصفات API الخاصة بك ككود إلى إزالة كل هذا. الملف هو المواصفات. Git هو التاريخ. تقوم خطة الأتمتة الموجودة لديك بالباقي. نغطي هذا المبدأ بالتفصيل في مواصفات API ككود.

كيف يعمل وضع Apidog Spec-First Mode

تم تصميم وضع Spec-First Mode للفرق التي تفكر بالفعل في الالتزامات والفروع. تقوم بتصميم API كملفات YAML أو JSON خام، ويحافظ Apidog على مزامنة هذه الملفات مع مستودع Git الخاص بك في كلا الاتجاهين.

إليك ما تحصل عليه.

محرر OpenAPI بأسلوب IDE

تكتب المواصفات في محرر أكواد، وليس نموذجًا. يوفر المحرر التسهيلات التي تتوقعها من بيئة التطوير المتكاملة (IDE):

تمييز بناء الجملة لـ YAML و JSON.
التحقق من صحة مخططات OpenAPI و Swagger، بحيث تظهر الأخطاء أثناء الكتابة.
الإكمال التلقائي للكلمات الرئيسية والأنواع والمراجع الخاصة بـ OpenAPI.

تبقى مسيطرًا على الملف بالضبط. لا توجد حقول مخفية، ولا بيانات وصفية خاصة بواجهة المستخدم فقط.

ملفات YAML/JSON الخام

المواصفات هي ملف حقيقي. جزء صغير منه:

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 properties:
 id:
 type: string
 status:
 type: string
 enum: [pending, shipped, delivered]

هذا هو الملف الذي يصل إلى مستودعك. ما تعدله هو ما يتم الالتزام به.

مخطط تفصيلي قابل للتصفح يتم تحليله تلقائيًا

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

تبقى المواصفات الطويلة قابلة للتصفح. اقفز إلى نقطة نهاية دون التمرير عبر مئات الأسطر.

مزامنة Git ثنائية الاتجاه

يتصل وضع Spec-First Mode بمزود Git الخاص بك ويزامن التغييرات في كلا الاتجاهين. وهو يدعم GitHub و GitLab مباشرة، و Azure DevOps من خلال اتصال Git.

اسحب التغييرات التي دفعها زملاؤك. قم بالتحرير محليًا في محرر Apidog. ثم قم بالالتزام والدفع مرة أخرى إلى نفس الفرع. يبقى المستودع ومساحة عملك متوافقين.

التزام، دفع، ومؤشر حالة المزامنة

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

هذه المزامنة ثنائية الاتجاه هي جوهر سير عمل API الأصلي لـ Git. للحصول على شرح مركز لجانب GitHub، راجع مزامنة مواصفات OpenAPI مع GitHub.

شرح الإعداد

إليك كيفية الانتقال من مستودع فارغ إلى مواصفات متزامنة. المرجع الكامل موجود في وثائق وضع Spec-First Mode.

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

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

اكتب رسالة التزام. صف التغيير بلغة واضحة، بنفس الطريقة التي تفعلها في أي عميل Git. "إضافة استجابة 404 لـ getOrder" أفضل من "تحديث المواصفات".
ادفع. أرسل الالتزام إلى الفرع المتتبع. يرى زملاؤك وخط أنابيب CI الخاص بك الآن الإصدار الجديد.

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

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

وضع Spec-first مقابل وضع Design-first

يدعم Apidog طريقتين للعمل. الفرق هو أين تعيش المواصفات وكيف تقوم بتحريرها.

	وضع Spec-First (تجريبي)	وضع Design-First
تخزين المواصفات	ملفات YAML/JSON خام في Git	مشروع Apidog السحابي
المحرر الأساسي	محرر أكواد بأسلوب IDE	واجهة مستخدم بصرية تعتمد على النماذج
التحكم في الإصدارات	Git أصلي (التزامات، فروع، فروق)	سجل Apidog وفروعه
مزامنة Git ثنائية الاتجاه	نعم (GitHub, GitLab, Azure DevOps)	عبر التصدير/الاستيراد
الأفضل لـ	الفرق التي تعيش في Git	الفرق التي تفضل سير عمل مرئي

لا يوجد وضع "أفضل" من الآخر. يخدمان عادات مختلفة. إذا كانت عملية المراجعة والإصدار الخاصة بك تعمل بالفعل على Git، فإن وضع Spec-First يزيل الفجوة. إذا كان فريقك يصمم بصريًا ونادرًا ما يلمس OpenAPI الخام، فقد يكون وضع Design-First أفضل ملاءمة.

متى تستخدمه

اختر وضع Spec-First عندما:

يجب أن تمر مواصفاتك عبر طلبات السحب ومراجعة الكود.
تريد git blame وسجل التزام حقيقي لعقد API الخاص بك.
يقوم CI الخاص بك بتشغيل فحص المواصفات، أو اختبارات العقود، أو توليد الكود التي تحتاج إلى ملف على القرص.
يقوم عدة مهندسين بتحرير المواصفات وتريد فروقًا نظيفة وقابلة للدمج.
تعبت من التصدير من أداة واحدة لتغذية أخرى.

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

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

ما هو سير عمل API الأصلي لـ Git؟

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

هل يدعم Apidog Spec-First Mode GitHub و GitLab؟

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

هل يمكنني تحرير ملفات OpenAPI كـ YAML أو JSON خام؟

نعم. يوفر وضع Spec-First محررًا بأسلوب IDE لملفات YAML و JSON الخام، مع تمييز بناء الجملة، والتحقق من صحة المخطط، والإكمال التلقائي لـ OpenAPI و Swagger. يقوم مخطط الشريط الجانبي الأيسر بتحليل الملف تلقائيًا حتى تتمكن من التنقل في المواصفات الكبيرة بسرعة.

ما الفرق بين وضع Spec-First و Design-First؟

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

الخاتمة

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

يمنحك وضع Apidog Spec-First Mode محررًا بأسلوب IDE، والمخطط التفصيلي القابل للتصفح، ومزامنة Git ثنائية الاتجاه لجعل ذلك حقيقة. يمكنك تحرير YAML أو JSON الخام، والالتزام برسالة واضحة، والدفع، ومشاهدة الحالة تقرأ "تمت المزامنة الآن."

جرب وضع Spec-First وأعد مواصفات API الخاصة بك إلى Git.

زر