يوجد معسكران في كل فريق واجهة برمجة تطبيقات (API) عملت معه.
أحدهما يكتب مواصفات OpenAPI الخاصة به يدويًا، ويلتزم بها في دليل specs/، ويعامل Git كمصدر للحقيقة. والآخر ينقر عبر مصمم مرئي، ويصدر المواصفات عندما تشتكي CI، ويرقع أي اختلاف تراكم بين التمثيلين منذ يوم الثلاثاء الماضي.
لقد عشت في كلا المعسكرين. الأول أبطأ في اليوم الأول وأسرع في اليوم التسعين. الثاني هو العكس. وحتى قبل حوالي شهر، كانت أداة تصميم API التي أستعين بها كثيرًا — Apidog — تلبي احتياجات المعسكر الثاني فقط. مصممها المرئي ممتاز. وكان تبادل YAML ذهابًا وإيابًا ميزة كان عليك الدفاع عنها في مراجعة الكود.
ثم في منتصف أبريل، ظهر وضع Spec-First (بيتا) في مربع حوار مشروع جديد. لم أكتب عنه عمدًا في يوم الإطلاق. أردت استخدامه في شيء حقيقي أولاً، وأردت الانتظار لوقت كافٍ لتظهر الأخطاء المبكرة. شهر هو تقريبًا الوقت المناسب. هذا المنشور هو ما وجدته بعد قضاء صباح مع النسخة التجريبية مقابل مواصفات OpenAPI من أحد مشاريعي الجانبية — ما سأقوله لزميل قبل أن يجربه، وأين يتناسب وأين لا يتناسب.
ما الذي يغيره وضع "المواصفات أولاً" بالفعل
النسخة القصيرة: يحتوي Apidog الآن على وضعين للمشاريع، وهما في الواقع منتجان مختلفان تمامًا تحت الغطاء.
الوضع الافتراضي هو ما يعرفه معظم الناس. تنقر على + مشروع جديد، تحصل على شجرة من المجلدات والنماذج المرئية، وتقوم بإنشاء نقاط النهاية عن طريق ملء الحقول. يتم إنشاء مواصفات OpenAPI تحت الغطاء. وهو يعمل، خاصة للفرق التي ليس لديها عادة YAML قوية بالفعل.
يستبدل وضع "المواصفات أولاً" محرر النماذج بمحرر أكواد حقيقي فوق ملفات .yaml و .json الخام، بالإضافة إلى مزامنة ثنائية الاتجاه مع مستودع Git الخاص بك. مواصفات OpenAPI الخاصة بك هي الملف الموجود على القرص، وليست تسلسلًا للنقرات. يوجد تمييز نحوي، وإكمال تلقائي مقابل مخطط OpenAPI، ولوحة "تحليل الدليل في الوقت الفعلي" التي تبني مخططًا لنقاط النهاية في الشريط الجانبي من الكود الخاص بك أثناء الكتابة.
هذه التفصيلة الأخيرة هي ما سأبدأ به لو كنت أعرض هذا على متشكك. سبب وجود المصممين المرئيين ليس لأن YAML صعب — بل لأنه يخفي الهيكل حتى تتجاوزه بالفعل. عرض المخطط في Apidog يحل ذلك دون إجبارك على التخلي عن الملف. تكتب المواصفات، تحصل على التنقل. الاثنان يتعايشان على الشاشة.
الفرضية، إذا كان هناك فرضية: تطوير المواصفات أولاً لم يكن يتعلق أبدًا بتفضيل محررات النصوص. كان يتعلق بمن يمتلك الأثر. وضع المواصفات أولاً يجعل الأثر هو الملف في مستودعك، نقطة. واجهة المستخدم هي نافذة عليه، وليست غلافًا حوله.
الإعداد، من البداية إلى النهاية
هذا هو المسار الذي سلكته. استغرق الأمر أقل من عشر دقائق، كان معظمها يتعلق بتفويض Git.
1. إنشاء المشروع في الوضع الصحيح. من شاشة المشاريع، انقر على + مشروع جديد ← عام ← وضع المواصفات أولاً. قد يكون محدد الوضع سهل التجاوز إذا كنت تنشئ المشاريع تلقائيًا لمدة عام — يتم وضع علامة "موصى به" على الوضع العام وتنزلق عينك مباشرةً بعد المربع الثاني. تباطأ هنا.
2. الاتصال بمستودع Git الخاص بك. انتقل إلى الاتصال بمستودع Git وقم بتفويض مزودك. لقد استخدمت GitHub؛ توثيقات تغطي الآخرين. ثم اختر المنظمة، المستودع، والفرع الرئيسي. سيقوم Apidog بمزامنة ملفات المواصفات في هذا الفرع كنسخة عمل لديك.
3. تهيئة المشروع. أدخل اسم المشروع، واضبط أذونات الفريق، ثم انقر على إنشاء. تسحب المزامنة الأولى أي ملفات .yaml و .json موجودة في المستودع إلى مساحة عمل Apidog.
4. تحرير المواصفات كملف، وليس كنموذج. افتح أحد ملفات YAML. تحصل على محرر حقيقي، وإكمال تلقائي يراعي المخطط، ومخطط نقطة النهاية الذي يظهر في الشريط الجانبي أثناء الكتابة. إذا قضيت أي وقت في VS Code مع إضافة OpenAPI، فسيبدو هذا مألوفًا — إلا أن المخطط مرتبط بالتنقل، والنقر على نقطة نهاية يقفز إلى السطر الصحيح.
5. الالتزام والدفع (Commit and Push). في أعلى اليمين، انقر على الالتزام والدفع. يفتح مربع الحوار قسم التغييرات الذي يسرد الملفات المعدلة، وحقل رسالة الالتزام، وزرين: دفع أو التجاهل جميع التغييرات. لا توجد خطوة منفصلة للتجهيز — أي شيء في التغييرات سيذهب إلى الالتزام. وهذا تبسيط مقصود، وبالنسبة لمعظم سير عمل تحرير المواصفات، فهو القرار الصحيح.
6. راقب مؤشر المزامنة. في الزاوية السفلية اليسرى — يمكنك رؤيته كـ تمت المزامنة الآن في الشكل 1. يخبرك ما إذا كانت تعديلاتك المحلية قد تم دفعها، سحبها، أو غير متزامنة مع الخادم البعيد. لقد تركت هذا مفتوحًا في زاوية من شاشتي وأصبح الشيء الذي أثق به أكثر من مربعات الحوار المنبثقة. إذا كان المؤشر أخضر، فأنت والمستودع متفقان.
هذه هي المساحة السطحية بأكملها. ست خطوات، لا يوجد محرك مزامنة منفصل لتهيئته، لا توجد إضافات لتثبيتها.
ما لاحظته ولم تخبرك به المستندات
ثلاثة أمور تستحق الإشارة إليها، جميعها من صباح قضيتها في استكشاف الأمر.
يتم تحديث عرض المخطط أسرع مما توقعت. لقد استخدمت العديد من "محررات OpenAPI المباشرة" في الماضي، ومعظمها يعيد التحليل عند الحفظ، مما يعني تأخيرًا لمدة 30 ثانية بين إضافة نقطة نهاية ورؤيتها في الشريط الجانبي. تحدّث مخطط Apidog أثناء الكتابة — قريبًا جدًا من الفورية لدرجة أنني توقفت عن التحقق. يبدو هذا شيئًا صغيرًا. لكنه ليس كذلك. إنه الفرق بين الثقة في المخطط كمساعد للتنقل وبين التحقق منه كتقرير حالة.
تكامل Git ذو اتجاهين بالفعل. قمت بتحرير نفس الملف في نسختي المحلية وقمت بالدفع من الطرفية بينما كان Apidog مفتوحًا. لاحظ Apidog ذلك، وتحول مؤشر المزامنة إلى "متأخر"، وبنقرة واحدة تم سحب التغييرات إلى المحرر بدون مربع حوار للدمج. المزامنة ثنائية الاتجاه التي تعد بها المستندات هي التجربة الفعلية، وليست ملخصًا تسويقيًا. إذا كان لديك زميل في الفريق يرفض استخدام أي شيء سوى Vim، فيمكنه الاستمرار في استخدام Vim، ويمكنك الاستمرار في استخدام Apidog، ويبقى الملف في المستودع هو الشيء الوحيد الذي يقوم كلاكما بتحريره.
لا يوجد مخرج للعودة إلى المصمم المرئي في نفس المشروع. هذا مقصود، ولكنه يستحق المعرفة قبل الالتزام. إذا اخترت وضع المواصفات أولاً عند الإنشاء، فإن هذا المشروع يكون مواصفات أولاً. لا يمكنك تبديل مشروع في منتصف الطريق لأن نماذج البيانات الأساسية مختلفة. بالنسبة للفريق الذي يريد كلا الوضعين على نفس المواصفات، فإن سير العمل هو: الاحتفاظ بالمواصفات في مستودع، وتوجيه مشروع يعتمد على المواصفات أولاً إليه، والسماح لمستخدمي الوضع المرئي بفتح مشروع منفصل يستورد من نفس المصدر. ليس سلسًا، ولكنه قابل للعمل.
أين يتناسب، وأين لا يتناسب
سأستخدم هذا في الإنتاج. هذا هو الجواب الأكثر مباشرة الذي يمكنني تقديمه. إن الجمع بين محرر حقيقي، وإكمال تلقائي يحترم مخطط OpenAPI، ومؤشر مزامنة يمكنني الوثوق به، هو ما كنت أريده من Apidog لمدة عامين.
ولكن هذه هي النسخة الصادقة لمن هذا مخصص.
إنه يتناسب إذا كنت تكتب OpenAPI يدويًا بالفعل، أو ترغب في ذلك. إنه يتناسب إذا كانت أدوات CI الخاصة بك تقوم بتشغيل spectral lint أو تولد حزم SDK للعميل من المواصفات وتحتاج المواصفات إلى العيش في Git على أي حال. إنه يتناسب إذا كان لديك مهندس في الفريق سيقوم بخلاف ذلك بفتح طلبات سحب ضد ملف YAML من VS Code، وتريد أن يتفق الجميع على أداة واحدة دون إجبارهم على ترك لوحة المفاتيح. ويتناسب بشكل خاص إذا كنت تدير التباين بين "المواصفات في Apidog" و "المواصفات في المستودع" بخطوة make export لا يثق بها أحد.
إنه لا يتناسب إذا لم يلمس فريقك OpenAPI مطلقًا وكان المصمم المرئي هو السبب وراء قدرتهم على المساهمة. بالنسبة لهؤلاء الفرق، لا يزال الوضع الافتراضي هو الخيار الصحيح. يتنازل وضع "المواصفات أولاً" عن سهولة الإعداد مقابل الدقة، وهذا التنازل خاطئ عندما لا يكون معظم المساهمين لديك متخصصين في واجهة برمجة التطبيقات.
كما أنه لا يتناسب، حتى الآن، للفرق التي تحتاج إلى خلط كلا الوضعين في نفس المشروع. النسخة التجريبية هي بالفعل نسخة تجريبية على هذا الصعيد. أتوقع أن يتغير هذا في الإصدارات القليلة القادمة.
الخلاصة
كان تطوير المواصفات أولاً يعني في السابق التخلي عن أدوات تصميم واجهة برمجة التطبيقات. فإما أن تعيش في YAML وتتخلى عن أدوات تشغيل الاختبارات والخوادم الوهمية، أو أن تعيش في مصمم مرئي وتتخلى عن Git كمصدر للحقيقة. الخطوة المثيرة للاهتمام في وضع "المواصفات أولاً" هي أن Apidog توقف عن مطالبتك بالاختيار.
الملف في مستودعك هو الملف في المحرر. المخطط هو عرض، وليس حالة. مزامنة Git هي السلك، وليست ميزة. إذا كنت تنتظر منصة واجهة برمجة تطبيقات تأخذ مفهوم "المواصفات أولاً" على محمل الجد بدلاً من التعامل معه كخيار تصدير، فهذه هي المنصة التي أنصحك بتجربتها.
النسخة التجريبية متاحة في مربع حوار "مشروع جديد" اليوم. قم بتنزيل Apidog، اختر وضع "المواصفات أولاً" عند الإنشاء، ووجهه إلى مستودع تثق به بالفعل. الالتزام الأول يستغرق عشر دقائق. قرار الاحتفاظ به يستغرق حوالي أسبوع.
button