دليل ترحيل ستوبلايت إلى ايبيدوج: إدارة مواصفات OpenAPI في نمط المواصفات أولاً

الهجرة من Stoplight إلى Apidog لا تتعلق فقط باستيراد ملف OpenAPI. بل تتعلق بتحويل سير عمل API المعتمد على الملفات.

بالنسبة للعديد من الفرق، تضمنت مشاريع Stoplight أكثر من مجرد نقاط نهاية: مواصفات OpenAPI في Git، ومستندات Markdown، ونماذج JSON Schema، وصور محلية، ومدخلات التنقل المدعومة في toc.json، وإعدادات المسار المدعومة في .stoplight.json.

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

وضع Apidog Spec-first Mode يساعد الفرق على الاحتفاظ بملفات OpenAPI كـ مصدر وحيد للحقيقة أثناء الهجرة من Stoplight، مع ربط تلك الملفات بمساحة عمل API أوسع للوثائق، والمحاكاة، والاختبارات، والتقارير، والأذونات، والتعاون.

يشرح هذا الدليل كيفية تخطيط عملية الهجرة تلك: ما الذي يمكن نقله، وما الذي يجب مراجعته، وما الذي يحتاج إلى إعادة بناء، وما الذي يجب ربطه حول عقد OpenAPI.

للاطلاع على خطوات الإعداد التشغيلي، راجع دليل المساعدة الخاص بوضع Spec-first Mode.

لماذا الهجرة من Stoplight هي أكثر من مجرد استيراد ملف OpenAPI

يصف ملف OpenAPI عقد الـ API. وعادةً ما يحتوي المشروع على غرار Stoplight على سياق إضافي حول هذا العقد.

تشمل أصول المشروع الشائعة ما يلي:

• ملفات OpenAPI أو Swagger، وغالباً ما تُخزن تحت reference أو دليل آخر مُكوّن؛
• وثائق Markdown، وغالباً ما تُخزن تحت docs؛
• ملفات نماذج JSON Schema، وغالباً ما تُخزن تحت models؛
• الصور المحلية المشار إليها في الوثائق؛
• ملف .stoplight.json لإعدادات المسار المدعومة؛
• ملف toc.json لمدخلات تنقل الوثائق المدعومة، والتجميع، والترتيب؛
• معرفات Stoplight مثل x-stoplight-id أو x-stoplight.id.

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

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

نموذج الهجرة: النقل، المراجعة، إعادة البناء، الربط

قبل البدء، حدد مصدر الحقيقة الفعلي. إذا كانت ملفات OpenAPI في Git هي التي تحدد عقد الـ API، فيمكن أن تبدأ الهجرة بوضع Spec-first Mode من تلك الملفات. وإذا كانت مجموعات Postman أو Bruno هي التي تقود سير عمل الطلبات الفعلي، فحل هذا التضارب أولاً.

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

استخدم نموذجًا من أربعة أجزاء بدلاً من ذلك:

هذا التمييز مهم لأن الهجرة من Stoplight تتضمن طبقتين.

الطبقة الأولى هي طبقة الملفات: مواصفات OpenAPI، مستندات Markdown، ملفات النماذج، الصور، وملفات هيكل المشروع. وهنا يكون وضع Spec-first Mode مفيدًا بشكل مباشر.

الطبقة الثانية هي طبقة سير العمل: كيف يراجع فريقك تغييرات الـ API، وينشر الوثائق، ويجري الاختبارات، ويدير المحاكيات، ويشارك التقارير، ويتعاون عبر فرق الواجهة الخلفية، والواجهة الأمامية، وضمان الجودة، والمنتج، والشركاء. يجب ألا تُعامل هذه الطبقة كنتيجة ثانوية للاستيراد. فهي المكان الذي يمكن فيه لـ Apidog ربط العقد ببقية دورة حياة الـ API.

كيف يتناسب وضع Apidog Spec-first Mode مع مشاريع Stoplight

تم تصميم وضع Spec-first Mode في Apidog لسير العمل المعتمد على الملفات — وهو بالضبط ما يستخدمه مشروع Stoplight الخاص بك بالفعل.

تحافظ المشاريع المتصلة بـ Git على مستودعك في المركز. يبقى فرعك هو مصدر الحقيقة، ويتزامن Apidog معه.

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

توفر لك مساحة عمل المواصفات (Specs workspace) مكانًا واحدًا لإدارة ملفاتك المصدرية، ورؤية هيكل API المُحلل لديك، والتعامل مع جميع سير عمل التحرير الخاص بك.

إليك كيفية عمل كل نوع من أصول Stoplight في Apidog:

ملاحظات التوافق لملفات مشروع Stoplight

• يجب معاملة .stoplight.json كمجموعة فرعية مدعومة من إعدادات المسار للمزامنة. يمكن لـ Apidog استخدام أدلة الجذر المدعومة لـ OpenAPI وMarkdown وJSON Schema، وأنماط تضمين OpenAPI، وأنماط الاستبعاد العالمية، وtocPath. يجب معاملة إعدادات مشروع Stoplight الأخرى على أنها مهملة ما لم يتم التحقق منها.
• يمكن لـ toc.json أن يساعد في إعادة بناء دلالات التنقل المدعومة في Apidog، بما في ذلك مجلدات DOCS، وترتيب Markdown، وروابط OAS/الوحدات، وروابط عناصر المواصفات المختارة، واستيراد نماذج المشار إليها في TOC. لا يزال الشريط الجانبي النهائي يُعرض من خلال نموذج DOCS/OAS/MODELS الخاص بـ Apidog، لذلك قد لا يتم الحفاظ على تخطيطات Stoplight العشوائية والترتيب الدقيق عبر الأنواع. لا يقوم toc.json بتخصيص الشريط الجانبي للوثائق عبر الإنترنت بشكل كامل.
• يتم ترحيل الصور بشكل أساسي عندما تتم الإشارة إليها بواسطة Markdown. يجب مراجعة الأصول غير المشار إليها والصور الخارجية ومعرفات URI للبيانات بشكل منفصل.
• تكون ملفات JSON Schema الأكثر قابلية للتنبؤ عندما تتم الإشارة إليها صراحةً بواسطة هيكل المشروع المدعوم، مثل toc.json، بدلاً من افتراضها من دليل بمفرده.

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

من استيراد الملف إلى سير عمل API المتصل

في سير عمل الاستيراد التقليدي، غالبًا ما تستورد الفرق ملف OpenAPI مرة واحدة ثم تواصل العمل بصريًا في الأداة الجديدة. قد يؤدي ذلك إلى حدوث تباين: قد لا يمثل الملف في Git، والوثائق، ومساحة عمل API نفس مصدر الحقيقة.

يختلف وضع Spec-first Mode. فالملفات تظل هي الأساس.

في مشروع Spec-first متصل بـ Git، يمكن للفرق تحرير الملفات في مساحة عمل المواصفات (Specs workspace)، ثم تنفيذ التغييرات ودفعها مرة أخرى إلى المستودع. في مشروع مدعوم بالملفات، يمكن للفرق تحرير وحفظ ملفات المواصفات داخل Apidog قبل ربط Git.

التقسيم العملي هو:

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

هذا هو الفرق بين نقل البيانات ونقل سير العمل. استيراد ملف ينقل العقد مرة واحدة. ربط مشروع Spec-first يمنح الفريق مساحة عمل حول العقد.

مسارات الهجرة: المتصلة بـ Git مقابل المدعومة بالملفات

لا تبدأ جميع فرق Stoplight بنفس مستوى نضج سير العمل.

تراجع بعض الفرق بالفعل كل تغيير في الـ API من خلال فروع Git وطلبات السحب (pull requests). بينما لدى البعض الآخر مواصفات ووثائق API كملفات، لكنهم ليسوا مستعدين لجعل مزود Git خارجي جزءًا من الإطلاق الأول.

يدعم وضع Apidog Spec-first Mode كلا المسارين.

بالنسبة لمعظم عمليات الهجرة من Stoplight، تعد المشاريع المتصلة بـ Git هي النموذج الأوضح على المدى الطويل لأن المستودع يظل مصدر الحقيقة للعقد.

تعد المشاريع المدعومة بالملفات مفيدة عندما يرغب الفريق في تقييم تجربة التأليف، أو تنظيف ملفات المشروع، أو إعداد الهجرة قبل اعتماد سير عمل Git أكثر صرامة.

ما الذي يجب مراجعته بعد الهجرة

حتى عندما يمكن نقل ملفات المشروع، يجب أن تتضمن عملية الهجرة مراجعة. هذا مهم بشكل خاص للفرق التي لديها مواقع وثائق كبيرة، أو العديد من ملفات المخططات (schema files)، أو تنقل Stoplight مخصصًا.

استخدم قائمة التحقق هذه بعد إنشاء مشروع Spec-first.

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

ماذا عن أصول Postman و Bruno؟

تستخدم العديد من فرق Stoplight أيضًا Postman أو Bruno. يجب تخطيط هذه الأصول بشكل منفصل عن هجرة OpenAPI.

تحدد ملفات OpenAPI عقد API. وعادةً ما تحدد مجموعات Postman وملفات .bru الخاصة بـ Bruno سير عمل الطلبات، والأمثلة، والبيئات، أو الاختبارات. يمكن أن تكون ذات قيمة، لكنها ليست نفس كائن الهجرة كـ مشروع OpenAPI على غرار Stoplight.

قبل الهجرة، أجب عن هذه الأسئلة:

لمستخدمي Bruno، الرؤية الرئيسية هي أن سير العمل الأصلي لـ Git ذو قيمة بالفعل. يمكن لوضع Spec-first Mode أن يحافظ على العقد المعتمد على الملفات، لكن أصول Bruno قد تظل بحاجة إلى هجرة منفصلة، أو إعادة بناء، أو استبدال حسب كيفية استخدام الفريق لها.

خطة الهجرة الموصى بها

استخدم خطة مرحلية بدلاً من محاولة نقل كل سير عمل API دفعة واحدة.

خطة هجرة مرحلية: انقل عقد OpenAPI أولاً، ثم أعد ربط سير العمل المحيط به.

1. تدقيق المستودع على غرار Stoplight

حدد ملفات OpenAPI، و.stoplight.json، وtoc.json، ومستندات Markdown، والنماذج، والصور، وأي أصول طلبات أو اختبارات ذات صلة.

2. تحديد مصدر الحقيقة

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

3. إنشاء مشروع Spec-first

اختر مشروعًا متصلًا بـ Git إذا كان الفريق مستعدًا للحفاظ على Git كمصدر للحقيقة. اختر مشروعًا مدعومًا بالملفات إذا كان الفريق يرغب في التحقق من صحة سير عمل الملفات أولاً.

4. مراجعة ما تم نقله

تحقق من الوحدات، والوثائق، والنماذج، والصور المشار إليها، والروابط، ومدخلات التنقل المدعومة في toc.json، وإعدادات المسار المدعومة في .stoplight.json، ونتائج التحقق من المواصفات (Specs validation). قم بإصلاح ملفات المشروع حيثما أمكن بدلاً من ترقيع الأعراض يدويًا.

5. إعادة بناء الأصول على مستوى سير العمل

أعد ربط المحاكيات، والاختبارات، وأمثلة الطلبات، ومهام CI، والتقارير، والأذونات، ومسؤوليات النشر حول عقد API المهاجر.

6. تشغيل أول تغيير حقيقي من خلال سير العمل الجديد

قم بإجراء تغيير صغير على OpenAPI، وراجعه، وقم بمزامنته، وحدّث الوثائق إذا لزم الأمر، وتحقق من أن المحاكيات والاختبارات والتقارير اللاحقة تعمل كما هو متوقع.

إذا كان فريقك يدير بالفعل ملفات OpenAPI، ومستندات Markdown، ونماذج المخططات (schema models) في مستودع على غرار Stoplight، فيمكن لوضع Apidog Spec-first Mode أن يساعدك في اختبار مسار الهجرة قبل إعادة بناء سير العمل الكامل.

متى يتناسب مسار الهجرة هذا بشكل أفضل

هذا المسار للهجرة مناسب تمامًا عندما:

• يدير فريقك مواصفات OpenAPI أو Swagger كملفات؛
• يتضمن مشروع Stoplight الخاص بك مستندات Markdown، ونماذج، وصور، أو .stoplight.json، أو toc.json؛
• تعتمد عملية مراجعة API الخاصة بك بالفعل على فروع Git أو طلبات السحب (pull requests)؛
• ترغب في أن تظل وثائق API، والمحاكيات، والاختبارات، والتقارير، والتعاون متصلة بالعقد؛
• ترغب في تقليل الانجراف بين ملفات API ومساحة العمل المستخدمة من قبل فرق الواجهة الأمامية، وضمان الجودة، والمنتج، والمنصة، أو الشركاء.

قد يتطلب المزيد من التخطيط عندما:

• يكون مصدر الحقيقة الفعلي لـ API هو مجموعة Postman أو Bruno بدلاً من OpenAPI؛
• يعتمد مشروع Stoplight بشكل كبير على سلوك النشر المخصص؛
• تحتوي الوثائق على العديد من الروابط الخارجية، أو المرساها، أو الصفحات المولدة، أو الأصول غير المشار إليها؛
• يتم تخزين نماذج JSON Schema بتنسيقات أو هياكل تحتاج إلى مراجعة يدوية؛
• يرغب الفريق في إعادة إنشاء مثالية لتنقل Stoplight أو عرض الوثائق.

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

هل وضع Apidog Spec-first Mode بديل لـ Stoplight؟

يمكن استخدامه كبديل لـ Stoplight للفرق التي ترغب في الاحتفاظ بمشاريع OpenAPI المعتمدة على الملفات مع إضافة تعاون أوسع في API، والاختبار، والمحاكاة، والوثائق، والتقارير، وإدارة الأذونات حول تلك الملفات.

هل يمكنني الاحتفاظ بمواصفات OpenAPI في Git؟

نعم. في مشروع Spec-first متصل بـ Git، يمكن للفرق الاحتفاظ بـ Git كمصدر للحقيقة، ومزامنة فرع، وتحرير الملفات، وتنفيذ التغييرات مرة أخرى إلى المستودع.

هل أحتاج إلى Git للبدء؟

لا. يمكن استخدام مشروع Spec-first مدعوم بالملفات عندما يرغب الفريق في العمل بملفات المواصفات أولاً ثم ربط Git لاحقًا.

هل يتم الحفاظ على .stoplight.json و toc.json بالكامل؟

لا. يستخدم Apidog الأجزاء المدعومة من هذه الملفات كمدخلات للهجرة. يستخدم .stoplight.json بشكل رئيسي لاكتشاف المسار أثناء المزامنة، بما في ذلك جذور OpenAPI وMarkdown وJSON Schema المدعومة، وأنماط تضمين OpenAPI، والاستثناءات العالمية، وtocPath. يمكن لـ toc.json أن يساعد في تنظيم محتوى DOCS المدعوم، وروابط OAS/الوحدات، وروابط عناصر المواصفات المختارة، واستيراد نماذج المشار إليها في TOC. لا يزال الشريط الجانبي للوثائق عبر الإنترنت مقيدًا بنموذج DOCS/OAS/MODELS الخاص بـ Apidog، لذلك قد لا يتم الحفاظ على تنقل Stoplight الدقيق والترتيب التعسفي عبر الأنواع.

ماذا يحدث لمستندات Markdown؟

يمكن نقل مستندات Markdown إلى سير عمل مشروع Spec-first. عند وجود toc.json، يمكن لمستندات TOC المدرجة الاحتفاظ بمزيد من هيكلها حيثما كان ذلك مدعومًا. يجب مراجعة الروابط الداخلية، والمرساها، والصور، والعرض.

ماذا يحدث لنماذج JSON Schema؟

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

ماذا يحدث للصور؟

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

هل يجب أن أقوم بتشغيل التدقيق أو التحقق بعد الهجرة؟

نعم. بعد الهجرة، قم بتشغيل تحقق المواصفات (Specs validation) على ملفات OpenAPI المستوردة. يدعم Apidog التحقق من المحرر المستند إلى Spectral ويمكنه قراءة .spectral.yaml، .spectral.yml، .spectral.json، .spectral.mjs على مستوى الجذر، أو العودة إلى .stoplight/styleguide.json. استخدم النتائج لمراجعة مشاكل العقد والأسلوب؛ لا تتعامل مع نجاح التحقق كدليل على الحفاظ على كل سلوك خاص بـ Stoplight.

ماذا يجب أن يفعل مستخدمو Bruno أو Postman؟

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

هل يدعم Apidog أيضًا المحاكيات، والاختبارات، وCI/CD، والتقارير، والتعاون؟

نعم. يربط وضع Spec-first Mode عقد API المعتمد على الملفات بـ Apidog، ويمكن لمنصة Apidog الأوسع دعم الوثائق، والمحاكيات، وسيناريوهات الاختبار، وتنفيذ CI/CD باستخدام Apidog CLI، والتقارير، والأذونات، والتعاون الجماعي حول هذا العقد.

الخاتمة

لا ينبغي أن تعني الهجرة من Stoplight التخلي عن العمل بـ API المعتمد على الملفات.

يمكن أن يظل المستودع هو مصدر الحقيقة. يمكن أن تظل مواصفات OpenAPI، ومستندات Markdown، والصور المشار إليها، ونماذج JSON Schema المشار إليها في TOC، وملفات هيكل المشروع المدعومة قابلة للنقل والمراجعة. وفي الوقت نفسه، يمكن لسير عمل API حول تلك الملفات أن يصبح أكثر اتصالاً.

يوفر وضع Apidog Spec-first Mode لفرق Stoplight مسار هجرة عمليًا: نقل الأجزاء المستندة إلى الملفات من المشروع حيثما كان ذلك مدعومًا، ومراجعة هيكل Stoplight الخاص بعناية، وإعادة بناء الأصول على مستوى سير العمل حول مساحة عمل API متصلة.

إذا كان فريقك يقيم هجرة Stoplight، فابدأ بتدقيق هيكل مستودعك وتحديد الملفات التي تحدد عقد API. ثم استخدم وضع Spec-first Mode لربط تلك الملفات بالوثائق، والمحاكيات، والاختبارات، والتقارير، والأذونات، والتعاون في Apidog.

لتخطيط هجرة المؤسسات، راجع Apidog Enterprise.