تمنحك وحدة APIs في Apidog طريقتين لبناء نفس الشيء: عقد API. إحداهما تستخدم النماذج المرئية. والأخرى تستخدم محرر تعليمات برمجية خام متصل بـ Git. كلتا الطريقتين تنتج Open API صالحًا. يكمن الفرق في كيفية عمل فريقك يومًا بعد يوم، ويعتمد أي منهما يناسبك على عاداتك أكثر من اعتماده على الأداة.
يشرح هذا الدليل قرار التصميم أولاً مقابل المواصفات أولاً في Apidog: ما هو كل وضع، وكيف يتعاملان مع Git، وما هي الفرق التي تميل إلى اختيار أي منهما. يمكنك التبديل بينهما من مفتاح تبديل واحد في أسفل يسار وحدة APIs، لذا فإن الاختيار ليس دائمًا. لكن اختيار الوضع الافتراضي الصحيح يوفر الكثير من الاحتكاك.
الفلسفتان
قبل الأوضاع، العقلية. كلا النهجين يشتركان في قاعدة واحدة: تحدد عقد الـ API قبل كتابة التنفيذ. العقد هو مصدر الحقيقة. التعليمات البرمجية، والاختبارات، والمحاكاة، والوثائق كلها تنبع منه.
التصميم أولاً يعني أنك تشكل هذا العقد من خلال واجهة منظمة. تضيف نقاط النهاية، والمعلمات، والمخططات عبر النماذج والقوائم المنسدلة. تضمن الأداة أن الناتج صالح لأنك لا تستطيع إدخال سوى قيم صالحة.
المواصفات أولاً (غالبًا ما تسمى العقد أولاً) تعني أنك تكتب العقد مباشرة كملف مواصفات: OpenAPI في YAML أو JSON. المواصفات *هي* سطح عملك. تقوم بتحريرها مثل التعليمات البرمجية المصدر.
تتداخل هذه المصطلحات في الممارسة. "العقد أولاً" و "المواصفات أولاً" شبه مترادفين، وتستخدم العديد من الفرق مصطلح "التصميم أولاً" بشكل فضفاض ليعني أي نهج يسبق فيه العقد التعليمات البرمجية. التمييز المفيد هنا ملموس: في Apidog، يمنحك أحد الأوضاع نماذج، والآخر يمنحك محرر نصوص. هذا هو الخط الفاصل المهم عند الاختيار.
من الجدير بالذكر فصل كليهما عن تطوير API القائم على التصميم أولاً مقابل القائم على التعليمات البرمجية أولاً. تولد التعليمات البرمجية أولاً المواصفات *من* التعليقات التوضيحية في التنفيذ الخاص بك، لذا فالتعليمات البرمجية هي الرائدة. كلا وضعي Apidog يحافظان على العقد قبل التعليمات البرمجية. إنهما يختلفان فقط في كيفية تأليفها. للحصول على الصورة الأوسع لمعالجة المواصفات كقطعة أثرية ذات إصدار، راجع نظرتنا العامة حول سير عمل API الأصلي لـ Git.
وضع التصميم أولاً في Apidog
وضع التصميم أولاً هو المصمم المرئي. تقوم ببناء نقاط النهاية من خلال واجهة إرشادية: اختر طريقة، سم المسار، أضف معلمات الاستعلام والمسار، حدد مخططات الطلب والاستجابة من خلال محرر شجري، وأرفق أمثلة. يقوم Apidog بإنشاء OpenAPI الأساسي لك في الخلفية.
هذا الوضع هو الافتراضي لمعظم الفرق، ولسبب وجيه. لا تحتاج إلى تذكر بناء جملة OpenAPI. يفرض محرر المخطط البنية، لذلك لا يمكنك شحن مواصفات بقوس في غير محله أو نوع غير صالح. المكونات القابلة لإعادة الاستخدام، مثل مخطط Error المشترك أو رأس مشترك، على بعد بضع نقرات.
يدعم وضع التصميم أولاً أيضًا الفروع، حتى تتمكن الفرق من العمل على إصدارات منفصلة من تصميم API بالتوازي ومطابقتها لاحقًا. يرى المراجعون فرقًا منظمًا بدلاً من النص الخام، مما يجعل تغييرات العقد أسهل في القراءة للأشخاص الذين لا يعيشون في YAML.
المقايضة: أنت تعمل من خلال تجريد. إذا كنت تفكر بالفعل في OpenAPI، فقد تشعر النماذج وكأنها نقرات إضافية بينك وبين المواصفات التي لديك في ذهنك.
وضع المواصفات أولاً في Apidog
وضع المواصفات أولاً، المتوفر حاليًا في النسخة التجريبية، يقلب هذا. بدلاً من النماذج، تحصل على محرر تعليمات برمجية على غرار IDE وتكتب مواصفات OpenAPI أو Swagger مباشرة في YAML أو JSON. إنه مصمم للفرق التي تريد أن يعيش تعريف الـ API الخاص بها في Git مثل أي ملف مصدر آخر.
يتصرف المحرر مثل المحرر الموجود في محرر التعليمات البرمجية الخاص بك: تمييز بناء الجملة، والتحقق المضمن، والإكمال التلقائي المعد خصيصًا لمخططات OpenAPI و Swagger. أثناء الكتابة، يقوم شريط جانبي أيسر بتحليل المواصفات تلقائيًا إلى مخطط تفصيلي للمسارات والمكونات، حتى تتمكن من التنقل في ملف كبير دون التمرير. يشير مؤشر المزامنة إلى ما إذا كانت تعديلاتك المحلية متوافقة مع المستودع المتصل.
العنوان الرئيسي هو المزامنة ثنائية الاتجاه مع Git. يمكنك توصيل مستودع على GitHub أو GitLab (Azure DevOps يعمل من خلال اتصال Git عام)، ويقوم Apidog بمزامنة ملف المواصفات الخاص بك في كلا الاتجاهين. قم بالتحرير في Apidog، ثم التزم وادفع مباشرة من التطبيق. أو قم بتحرير المواصفات في محرر التعليمات البرمجية الخاص بك، وادفع من هناك، واسحب التغييرات مرة أخرى إلى Apidog. ملف المواصفات هو الحقيقة المشتركة، وكلا السطحين يظلان متوافقين. يمكنك قراءة الإعداد الكامل في وثائق وضع المواصفات أولاً.
يعالج هذا الوضع عقد الـ API الخاص بك بالطريقة التي ستعالج بها أي قطعة أثرية أخرى من التعليمات البرمجية: يتم مراجعتها في طلبات السحب، وتتبع إصداراتها جنبًا إلى جنب مع الخدمات التي تنفذها، ومقارنة سطر بسطر. إذا كانت هذه هي الطريقة التي يدير بها فريقك البنية التحتية والتكوين بالفعل، فراجع نظرتنا الأعمق حول مواصفات الـ API كتعليمات برمجية للحصول على الأسباب الكامنة وراء ذلك.
مقارنة جنبًا إلى جنب
كلا الوضعين ينتجان نفس OpenAPI ويدعمان المحاكاة والاختبار والوثائق النهائية. يختلفان في كيفية تأليف المواصفات وتتبع إصداراتها.
| وضع التصميم أولاً | وضع المواصفات أولاً (بيتا) | |
|---|---|---|
| المحرر | نماذج مرئية وشجرة مخطط | محرر تعليمات برمجية YAML/JSON على غرار IDE |
| تنسيق المواصفات | OpenAPI (يتم إنشاؤه لك) | OpenAPI / Swagger، مكتوب يدويًا |
| سير عمل Git | دعم الفروع داخل Apidog | مزامنة ثنائية الاتجاه مع GitHub وGitLab وAzure DevOps (اتصال Git)؛ الالتزام والدفع من التطبيق |
| التحقق من الصحة | يتم فرضه بواسطة مدخلات النموذج | التحقق المضمن من بناء الجملة والإكمال التلقائي |
| التنقل | قائمة نقاط النهاية والمجلدات | مخطط تفصيلي مُحلل تلقائيًا في الشريط الجانبي الأيسر |
| منحنى التعلم | منخفض؛ لا حاجة لمعرفة OpenAPI | أعلى؛ يفترض إتقان OpenAPI |
| الأفضل لـ | الفرق ذات المهارات المختلطة، والتأهيل السريع | المهندسون الذين يتعاملون مع المواصفات كتعليمات برمجية |
أي فريق يجب أن يختار أي وضع
استخدم وضع التصميم أولاً إذا لم يكن جميع المساهمين لديك خبراء في OpenAPI. يمكن لمديري المنتجات، ومراقبة الجودة، والمهندسين المبتدئين إضافة أو مراجعة نقاط النهاية دون تعلم بناء جملة المواصفات. إنه أيضًا المسار الأسرع عندما تبدأ API جديدًا من الصفر وترغب في التحرك بسرعة عبر الهيكل دون القلق بشأن التنسيق.
استخدم وضع المواصفات أولاً إذا كانت المواصفات الخاصة بك موجودة بالفعل، أو يجب أن تكون موجودة، في مستودع Git بجوار رمز الخدمة الخاص بك. ستشعر فرق الواجهة الخلفية التي تراجع تغييرات الـ API في طلبات السحب، وتشغل فحص المواصفات في CI، أو تريد ملف YAML أساسيًا واحدًا عبر الأدوات وكأنها في منزلها. تعني المزامنة ثنائية الاتجاه أن Apidog يتوقف عن كونه نسخة منفصلة من الحقيقة ويصبح نافذة على نفس الملف الذي يحتفظ به المستودع الخاص بك.
مسار عملي متوسط: العديد من الفرق تصمم نقاط نهاية جديدة في وضع التصميم أولاً للسرعة، ثم تنتقل إلى وضع المواصفات أولاً بمجرد نضج الـ API وتصبح مراجعة Git أولوية. الأوضاع ليست منتجات متنافسة. إنها رؤيتان لعقد واحد.
كيفية التبديل بين الأوضاع
التبديل هو مفتاح واحد. افتح وحدة APIs في مشروع Apidog الخاص بك وانظر إلى الزاوية السفلية اليسرى، حيث يوجد محول الوضع. اقلبه، وسيتم عرض العقد نفسه في الوضع الآخر.
بعض الأشياء التي يجب تذكرها عند التبديل:
- المواصفات الأساسية مشتركة، لذا فإن نقاط النهاية والمخططات والأمثلة الخاصة بك تنتقل عبرها. أنت تغير سطح التحرير، لا تعيد بناء الـ API.
- لاستخدام مزامنة Git في وضع المواصفات أولاً، قم بتوصيل مستودع GitHub أو GitLab أو Azure DevOps أولاً. بمجرد الاتصال، يخبرك مؤشر المزامنة ما إذا كانت تعديلاتك قد تم الالتزام بها ودفعها.
- نظرًا لأن وضع المواصفات أولاً في مرحلة تجريبية، جربه على مشروع حيث يمكنك تأكيد سلوك المزامنة قبل الاعتماد عليه لعقد إنتاجي.
يمكنك التنقل ذهابًا وإيابًا مع تغير احتياجاتك، لذا تعامل مع الاختيار كافتراضي بدلاً من التزام.
الأسئلة الشائعة
هل المواصفات أولاً هي نفسها العقد أولاً؟
في الممارسة العملية، نعم. "المواصفات أولاً" و "العقد أولاً" كلاهما يعني أنك تؤلف مواصفات الـ API قبل التنفيذ، وكلاهما يتعامل مع تلك المواصفات كمصدر للحقيقة. وضع المواصفات أولاً في Apidog هو سير عمل يعتمد على العقد أولاً حيث يكون العقد عبارة عن ملف OpenAPI أو Swagger مكتوب يدويًا ومتزامن مع Git.
هل يعمل وضع المواصفات أولاً مع GitLab و Azure DevOps؟
نعم. يدعم وضع المواصفات أولاً مزامنة Git ثنائية الاتجاه مع GitHub و GitLab مباشرة. يعمل Azure DevOps من خلال اتصال Git عام، بحيث يمكنك مزامنة ملف المواصفات الخاص بك مع مستودع مستضاف على Azure أيضًا.
هل يمكنني التبديل من وضع التصميم أولاً إلى وضع المواصفات أولاً دون فقدان عملي؟
نعم. يقرأ كلا الوضعين ويكتبان نفس العقد الأساسي، لذا تظل نقاط النهاية والمخططات والأمثلة الخاصة بك سليمة عند قلب مفتاح التبديل في أسفل يسار وحدة APIs. أنت تبدل المحرر، وليس البيانات.
لست متأكدًا أي منهما يناسب فريقك؟ افتح وحدة APIs، جرب مفتاح تبديل الوضع في أسفل اليسار، وصمم نقطة النهاية التالية بكلتا الطريقتين. العقد هو نفسه في كلتا الحالتين؛ اختر السطح الذي يتناسب مع كيفية عمل فريقك بالفعل.