قضيت صباحًا مع وضع Spec-First في Apidog: المصمم المرئي لم يعد البالغ الوحيد في الغرفة

يوجد نمطان شائعان داخل فرق تطوير واجهات برمجة التطبيقات: فريق يكتب مواصفات OpenAPI يدويًا داخل Git ويتعامل معها كمصدر الحقيقة، وفريق يستخدم مصممًا مرئيًا ثم يصدّر المواصفات عند الحاجة.

جرّب Apidog اليوم

جرّبت النمطين. الكتابة اليدوية أبطأ في البداية، لكنها أوضح وأكثر قابلية للمراجعة بعد أسابيع من التطوير. أما المصمم المرئي فهو أسرع في اليوم الأول، لكنه قد يخلق فجوة بين ما هو موجود في الأداة وما هو موجود في المستودع.

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

في هذا المقال أشرح كيف يعمل الوضع الجديد عمليًا، وكيف تُعدّه، ومتى يكون مناسبًا لفريقك.

ما الذي يغيّره وضع Spec-First فعليًا؟

في Apidog يوجد الآن نمطان مختلفان لإنشاء المشاريع:

1. الوضع العام

   • تبني الـ API عبر واجهة مرئية.
   • تضيف المسارات، الطلبات، الاستجابات، والمخططات من خلال نماذج.
   • يتم إنشاء مواصفات OpenAPI خلف الكواليس.

2. وضع Spec-First

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

الفكرة الأساسية: أنت لا “تصدّر” المواصفات من الأداة، بل تعدّل الملف نفسه الذي يعيش في المستودع.

openapi: 3.0.3
info:
  title: Store API
  version: 1.0.0

paths:
  /store/token:
    post:
      summary: Create store token
      responses:
        "200":
          description: Token created

عند إضافة مسار مثل /store/token، يظهر في المخطط الجانبي داخل Apidog دون الحاجة إلى الانتقال بين ملفات أو البحث يدويًا.

الميزة المهمة هنا ليست فقط تحرير YAML. يمكنك فعل ذلك في VS Code. القيمة الحقيقية هي أن Apidog يعرض بنية الـ API كتنقل حي فوق ملف المواصفات نفسه.

إعداد مشروع Spec-First خطوة بخطوة

هذا هو المسار العملي لإنشاء مشروع يعتمد على المواصفات أولًا.

1. أنشئ مشروعًا جديدًا بالوضع الصحيح

من شاشة المشاريع:

+ مشروع جديد → عام → وضع المواصفات أولاً

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

2. اربط المشروع بمستودع Git

بعد اختيار وضع Spec-First:

1. افتح خيار الاتصال بمستودع Git.
2. فوّض مزود Git الذي تستخدمه.
3. اختر:
   • المنظمة
   • المستودع
   • الفرع الرئيسي

استخدمت GitHub في التجربة، لكن الفكرة نفسها تنطبق على مزودي Git المدعومين.

3. هيّئ المشروع

أدخل:

• اسم المشروع
• إعدادات الفريق
• صلاحيات الوصول

ثم انقر إنشاء.

في أول مزامنة، يسحب Apidog ملفات .yaml و .json الموجودة في المستودع إلى مساحة العمل.

4. حرّر ملف OpenAPI مباشرة

افتح ملف YAML أو JSON من داخل المشروع. ستحصل على:

• تمييز نحوي
• إكمال تلقائي حسب OpenAPI Schema
• مخطط جانبي للمسارات
• تنقل مباشر إلى تعريف كل endpoint

مثال عملي لإضافة endpoint:

paths:
  /admin/auth:
    post:
      summary: Admin login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "200":
          description: Login successful
        "401":
          description: Invalid credentials

بعد الكتابة، يظهر المسار /admin/auth في الشريط الجانبي، ويمكنك النقر عليه للعودة إلى موضعه في الملف.

5. نفّذ Commit and Push

عند الانتهاء من التعديل:

1. انقر Commit & Push في أعلى اليمين.
2. راجع الملفات المعدلة في قسم التغييرات.
3. اكتب رسالة commit واضحة.
4. انقر Push.

مثال لرسالة commit مناسبة:

Add admin authentication endpoint to OpenAPI spec

لا توجد خطوة staging منفصلة. أي ملف ظاهر في قائمة التغييرات يدخل في commit.

6. راقب حالة المزامنة

في أسفل اليسار سترى مؤشر المزامنة، مثل:

تمت المزامنة الآن

هذا المؤشر يخبرك هل:

• التغييرات المحلية دُفعت إلى Git
• هناك تغييرات بعيدة تحتاج إلى سحب
• المشروع غير متزامن

عمليًا، هذا المؤشر مهم جدًا إذا كان أكثر من شخص يعدّل المواصفات.

ملاحظات عملية من التجربة

المخطط الجانبي يتحدث بسرعة

في بعض محررات OpenAPI، لا يظهر المسار الجديد إلا بعد الحفظ أو إعادة التحليل. في Apidog، المخطط الجانبي تحدّث أثناء الكتابة تقريبًا.

هذا يجعل المخطط أداة تنقل فعلية، وليس مجرد تقرير حالة بعد انتهاء العمل.

تكامل Git ثنائي الاتجاه

جرّبت تعديل الملف من الطرفية ثم دفع التغييرات إلى Git بينما كان Apidog مفتوحًا.

ما حدث:

1. اكتشف Apidog أن الفرع المحلي داخل الأداة متأخر.
2. تغيّر مؤشر المزامنة.
3. أمكن سحب التغييرات إلى المحرر.

هذا مهم إذا كان بعض أعضاء الفريق يفضلون Vim أو VS Code أو أي محرر آخر. طالما أن الجميع يعدّل الملف نفسه في Git، يمكن لكل شخص استخدام الأداة التي تناسبه.

لا يمكنك التحويل إلى المصمم المرئي داخل نفس المشروع

إذا أنشأت المشروع بوضع Spec-First، فهو يبقى مشروعًا قائمًا على المواصفات.

لا يوجد تبديل مباشر إلى الوضع المرئي داخل المشروع نفسه، لأن نموذج البيانات مختلف.

إذا احتجت إلى دعم النمطين، فالخيار العملي هو:

1. اجعل مستودع Git هو مصدر الحقيقة.
2. استخدم مشروع Spec-First للعمل على المواصفات.
3. استخدم مشروعًا منفصلًا يستورد من المصدر نفسه عند الحاجة إلى الواجهة المرئية.

هذا ليس مثاليًا، لكنه واضح وقابل للإدارة.

متى تستخدم Spec-First؟

استخدم هذا الوضع إذا كان فريقك:

• يكتب OpenAPI يدويًا بالفعل
• يراجع تغييرات الـ API عبر Pull Requests
• يشغّل أدوات مثل:

spectral lint openapi.yaml

• يولّد SDKs أو clients من ملف المواصفات
• يريد أن تكون المواصفات داخل Git بدل الاعتماد على export يدوي
• يحتاج إلى تقليل الفجوة بين “المواصفات في الأداة” و“المواصفات في المستودع”

مثال لسير عمل مناسب:

git checkout -b add-admin-auth
# تعديل openapi.yaml داخل Apidog
# Commit & Push من Apidog
# فتح Pull Request
# تشغيل CI للتحقق من المواصفات

متى لا تستخدمه؟

لا أنصح به إذا كان فريقك:

• لا يلمس OpenAPI مباشرة
• يعتمد بالكامل على الواجهة المرئية لفهم الـ API
• يضم مساهمين غير معتادين على YAML أو JSON
• يحتاج إلى مزج الوضع المرئي ووضع Spec-First داخل المشروع نفسه

في هذه الحالات، الوضع العام في Apidog ما زال مناسبًا أكثر.

خلاصة

وضع Spec-First في Apidog يجعل ملف OpenAPI داخل Git هو مصدر الحقيقة، بدل أن يكون ناتجًا يتم تصديره من أداة تصميم.

النتيجة العملية:

• تعدّل .yaml أو .json مباشرة.
• تحصل على إكمال تلقائي ومخطط جانبي.
• تزامن التغييرات مع Git من داخل الأداة.
• يستطيع الفريق استخدام Git كسير العمل الأساسي للمواصفات.

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