تباعد وثائق Swagger ومجموعات Postman: الأسباب والحلول

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

لماذا تنحرف الملفات دائمًا عن بعضها البعض

تحافظ على ملف openapi.yaml في مستودعك. وتحتفظ أيضًا بمجموعة Postman. يصف هذان الكائنان نفس عقد واجهة برمجة التطبيقات، ولكنهما مخزنان بشكل منفصل، ويتم تحريرهما بواسطة أشخاص مختلفين، ويتم تحديثهما في جداول زمنية مختلفة. لا يوجد شيء في أي من الأداتين يفرض الاتساق بينهما.

فكر في سيناريو واقعي. يقوم فريق الواجهة الخلفية بإطلاق نقطة نهاية POST /payments/refund جديدة مع حقل reason مطلوب. يضيف أحدهم هذا الحقل إلى مجموعة Postman لأن هذا هو المكان الذي يقومون فيه بتشغيل اختباراتهم. يتم وضع تحديث openapi.yaml في قائمة مهام Sprint. بعد ثلاثة أيام، يقرأ مطور الواجهة الأمامية وثائق Swagger، ويستدعي نقطة النهاية بدون reason، ويتلقى خطأ 400 لا يمكنه تفسيره من الوثائق وحدها.

السبب الجذري ليس الإهمال. إنه غياب أي ارتباط بين الأثرين. لا تعرف أي من الأداتين بوجود الأخرى.

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

مشكلة النسخ الثلاث

الفرق التي تستخدم أيضًا منصة توثيق منفصلة مثل Stoplight تزيد المشكلة تعقيدًا. الآن لديك ثلاث نسخ من العقد:

1. ملف openapi.yaml الملتزم به في Git.
2. مجموعة Postman المصدرة والمشار إليها كمساحة عمل.
3. الوثائق المعروضة في Stoplight (أو Swagger UI، أو ويكي).

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

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

كيف يكسر الانحراف الاختبارات بصمت

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

فيما يلي جزء YAML ملموس يوضح تغييرًا في المواصفات قد يتجاوزه مجموعة Postman غير المحدثة:

# openapi.yaml - updated spec (v2)
paths:
  /payments/refund:
    post:
      summary: Initiate a refund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_id
                - reason          # NEW required field added in v2
              properties:
                transaction_id:
                  type: string
                  example: "txn_8x9Ka21"
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]
                  example: "requested_by_customer"
      responses:
        '200':
          description: Refund initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund_id:
                    type: string
                  status:
                    type: string

ترسل مجموعة Postman المجمدة في الإصدار الأول transaction_id فقط. إذا أضاف فريق الواجهة الخلفية قيمة افتراضية متساهلة لـ reason أثناء النشر، فإن اختبار Postman القديم ينجح. تقول المواصفات إن reason مطلوب؛ الاختبار لا يرسله أبدًا. لا يلاحظ أحد حتى تنكسر عملية تكامل الواجهة الأمامية في مرحلة الاختبار.

تشغيل مدقق OpenAPI صحيح على ملف YAML الخاص بك يكتشف التناقضات في المخطط داخل المواصفات. لكنه لا يكتشف الفجوة بين المواصفات وما ترسله مجموعة Postman الخاصة بك فعليًا.

ماذا يعني الاختبار المدفوع بـ OpenAPI حقًا

الاختبار المدفوع بـ OpenAPI يعني أن المواصفات هي المصدر الموثوق. تُشتق الاختبارات منها، ولا تُكتب بالتوازي معها. عندما تتغير المواصفات، تعكس الاختبارات التغيير تلقائيًا لأنها تشترك في نفس المصدر.

هذا يختلف عن "استيراد Swagger إلى Postman". الاستيراد هو عملية نسخ لمرة واحدة. تضغط على استيراد، تحصل على مجموعة، ويصبح الكائنان مستقلين على الفور مرة أخرى. يتطلب تغيير المواصفات التالي استيرادًا يدويًا آخر أو تعديلًا يدويًا آخر للمجموعة. لم تحل مشكلة الانحراف؛ لقد أعدتها إلى الصفر.

التنفيذ الفعلي الذي يعتمد على المواصفات أولاً يبدو كالتالي:

1. يعيش ملف OpenAPI في Git كعقد أساسي.
2. تقوم أداة بقراءة هذا الملف وتستخلص منه المحاكاة والوثائق وحالات الاختبار.
3. عندما يتغير الملف (عبر مراجعة طلب السحب)، يتم تحديث المحاكاة وحالات الاختبار.
4. لا توجد مجموعة منفصلة للحفاظ على تزامنها.

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

Apidog كطبقة تنفيذ فوق مواصفة واحدة

يعالج نموذج Apidog Git كمصدر للحقيقة و Apidog كطبقة تنفيذ فوقه. تقوم بالالتزام بملف openapi.yaml الخاص بك. يقرأ Apidog هذا الملف وينتج ثلاثة مخرجات من ملف واحد: وثائق تفاعلية، خادم وهمي (mock server)، ومجموعة اختبار.

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

والنتيجة العملية هي أنه لا توجد مجموعة Postman لكي تنحرف. يوجد ملف واحد. يغطي سير عمل مزامنة مواصفات OpenAPI كيفية التزام الفرق بالمواصفات على GitHub والحفاظ على توافق Apidog.

بالنسبة للفرق التي تعتمد على سير عمل Postman، من المفيد التحقق في تجربة: كيف يتعامل Apidog مع سيناريوهات الاختبار المدفوعة بالبيانات مع تعقيد المخطط المحدد الخاص بك، وما إذا كانت أذونات رؤية التقارير تتطابق مع نموذج الوصول في مؤسستك. هذه أسئلة جيدة لمرحلة إثبات المفهوم (POC) قبل ترحيل مجموعة إنتاج.

تعد محاكاة واجهة برمجة التطبيقات (API mocking) أيضًا جزءًا مهمًا من الصورة. عندما يتم اشتقاق المحاكاة من نفس المواصفات التي تستخدمها الاختبارات، يحصل مطور الواجهة الأمامية الذي يستدعي المحاكاة على استجابة متوافقة مع ما تتحقق منه الاختبارات. لمزيد من المعلومات حول مكان تواجد المحاكاة، راجع حالات استخدام محاكاة واجهة برمجة التطبيقات.

كيف يبدو مسار الترحيل

إذا كنت قادمًا من إعداد Swagger + Postman، فإن الترحيل ليس استبدالًا شاملًا. تسلسل معقول:

1. راجع ملف openapi.yaml الحالي الخاص بك مقابل مجموعة Postman الخاصة بك. ابحث عن كل نقطة نهاية في المجموعة غير موجودة في المواصفات، وكل نقطة نهاية في المواصفات لا تغطيها المجموعة.
2. وفّق المواصفات. يجب أن تصف واجهة برمجة التطبيقات الحالية الفعلية، وليس واجهة برمجة التطبيقات كما كانت موجودة عندما كتبت YAML لأول مرة.
3. استورد المواصفات إلى Apidog. دع Apidog ينشئ مجموعة اختبار أولية من بنية المواصفات.
4. توقف عن استخدام مجموعة Postman تدريجيًا. قم بتشغيل كليهما بالتوازي لمدة Sprint واحد لمقارنة النتائج.
5. أرشفة المجموعة. يظل Git هو مصدر الحقيقة. يتعامل Apidog مع التنفيذ.

الخطوة 1 عادة ما تكون الأكثر إزعاجًا، لأنها تكشف مدى تباعد الأثرين. الفرق التي سمحت للانحراف بالتراكم لمدة ستة أشهر غالبًا ما تجد فجوات في تغطية نقاط النهاية تتراوح من 20 إلى 40 بالمائة.

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

مقارنة: صيانة مزدوجة مقابل المواصفات كمصدر

عمود الصيانة المزدوجة ليس فشلاً لـ Postman كأداة. Postman قوية في الاختبارات القائمة على المجموعات ولها نظام بيئي كبير. المشكلة هي نمط سير العمل في التعامل مع المجموعة كعقد موازٍ بدلاً من كونها أثراً مشتقاً.

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

لماذا لا يحل استيراد Swagger إلى Postman مشكلة الانحراف؟

الاستيراد ينشئ نسخة لحظية. بعد الاستيراد، يصبح الكائنان مستقلين. لا ينتشر التغيير التالي على ملف openapi.yaml الخاص بك إلى المجموعة تلقائيًا. ستحتاج إلى إعادة الاستيراد أو تعديل المجموعة يدويًا مع كل تغيير في المواصفات، مما يعيدك إلى مشكلة الصيانة المزدوجة.

هل يمكنني الاستمرار في استخدام Postman للاختبار الاستكشافي أثناء اعتماد نموذج يعتمد على المواصفات أولاً؟

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

كيف أعرف متى انحرفت مواصفاتي عن التنفيذ الفعلي لواجهة برمجة التطبيقات؟

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

هل يحل Apidog محل Postman بالكامل؟

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

ماذا لو كان ملف openapi.yaml الخاص بي قديمًا بالفعل؟

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

الخلاصة

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

قم بتنزيل Apidog واستورد مواصفات OpenAPI الحالية الخاصة بك. يمكنك أن ترى في جلسة واحدة كيف يحل ملف واحد محل وثيقة Swagger ومجموعة Postman الخاصة بك، مع قراءة المحاكاة والاختبارات والوثائق جميعها من نفس المصدر. إذا كنت تقوم بتقييم وضع "المواصفات أولاً" (Spec-First Mode) (المتاح حاليًا في مرحلة تجريبية)، فتحقق من صفحة وضع Apidog Spec-First Mode للحصول على نطاق الميزات الحالي وتفاصيل الوصول.