كيفية الترحيل من Stoplight إلى Apidog بنهج المواصفات أولاً

إذا كنت تنتقل من Stoplight Studio أو Stoplight Platform إلى Apidog، فإن أول شيء يجب أن تعرفه هو أنك لست بحاجة إلى إعادة تحميل مواصفات OpenAPI الخاصة بك. يتصل وضع Spec-First من Apidog (الذي لا يزال في مرحلته التجريبية حاليًا) مباشرةً بمستودع GitHub أو GitLab الحالي الخاص بك، لذا يظل Git هو مصدر الحقيقة ويبقى سجل الالتزامات الخاص بك سليمًا. يوضح هذا الدليل كل خطوة: تصدير إعدادات Stoplight الخاصة بك، وتعيين اتفاقيات الدليل الخاصة بها لتوقعات Apidog، واستبدال .stoplight.json و toc.json بمكافئاتهما في Apidog.

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

ما الذي يبقى كما هو عند الترحيل؟

لا تتغير ملفات OpenAPI الخاصة بك، ومستودع Git الخاص بك، واستراتيجية الفروع الخاصة بك. هذا هو المبدأ الأساسي. يقوم Stoplight بتخزين المواصفات كملفات YAML أو JSON يتم التحقق منها في التحكم بالمصدر. يقرأ Apidog نفس هذه الملفات عند ربط مستودع في وضع Spec-First.

ما يتغير هو كل شيء مضاف فوق ذلك: عارض التوثيق، وخادم الاختبار الوهمي (mock server)، ومشغل الاختبارات، وعميل API. فبدلاً من Stoplight Platform الذي يقدم الوثائق و Postman الذي يتعامل مع الاختبارات كأداة منفصلة، يجمع Apidog كل ذلك في مساحة عمل واحدة، متزامنة مع نفس ملف OpenAPI الذي يقوم مهندسوك بالفعل بالالتزام به.

الخلاصة العملية: ترحيلك هو في الغالب تبديل للإعدادات، وليس ترحيل بيانات.

الخطوة 1: تصدير أصول مشروع Stoplight الخاص بك

قبل البدء في Apidog، احفظ كل ما يحتفظ به Stoplight ولم يتم وضعه في Git بعد.

إذا كنت تستخدم Stoplight Studio مع واجهة Git خلفية:

تم الالتزام بمواصفات OpenAPI الخاصة بك ونماذج JSON Schema ووثائق Markdown بالفعل. قم بتشغيل git pull للتأكد من أن نسختك المحلية محدثة. يتبع Stoplight تنسيق مواصفات OpenAPI، وتعمل ملفات المواصفات هذه في Apidog دون تحويل. من المحتمل أن يبدو هيكل المستودع الخاص بك كما يلي:

your-api-repo/
  .stoplight.json          # Project config (needs replacement)
  reference/
    petstore.yaml          # Your OpenAPI spec(s)
  models/
    error.json             # Shared JSON Schema models
  docs/
    introduction.md        # Markdown guide pages
    authentication.md
  toc.json                 # Table-of-contents order (needs replacement)
  assets/
    images/
      architecture.png

إذا كنت تستخدم Stoplight Platform (مستضاف على السحابة، بدون واجهة Git خلفية):

صدّر مواصفاتك من واجهة مستخدم Stoplight: افتح كل مشروع API، وانتقل إلى "Export" (تصدير)، وقم بتنزيل OpenAPI YAML. بالنسبة لوثائق Markdown، انسخها إلى مجلد docs/ في مستودع Git جديد. لا يوفر Stoplight تصديرًا مجمعًا للمشاريع غير المستندة إلى Git، لذا قم بذلك لكل مشروع API.

بمجرد أن تكون ملفاتك في مستودع Git (GitHub أو GitLab)، انتقل إلى الخطوة التالية.

الخطوة 2: فهم ملفات التكوين التي تستبدلها

يقود ملفان خاصان بـ Stoplight هيكل المشروع. لا يوجد لأي منهما نظير مباشر في Apidog، ولكن فهم ما يفعلانه يوضح لك بالضبط ما يجب تكوينه في Apidog بدلاً من ذلك.

الرؤية الرئيسية: .stoplight.json و toc.json هما ملفان خاصان بـ Stoplight. يمكنك تركهما في المستودع (يتجاهل Apidog الملفات غير المعروفة)، لكنهما لن يشغلا أي شيء في Apidog. يمكنك تكوين الإعدادات المكافئة من خلال واجهة مستخدم مشروع Apidog.

الخطوة 3: ربط مستودعك بوضع Apidog Spec-First

وضع Apidog Spec-First هو الطريقة التي تربط بها مستودع GitHub أو GitLab بمشروع Apidog بحيث تُقرأ مواصفات OpenAPI دائمًا من Git، وليس من قاعدة بيانات Apidog داخلية. هذا يحافظ على Git كمصدر موثوق، ويعني أن مهندسيك يمكنهم الاستمرار في إرسال طلبات السحب (PRs) لتحديث المواصفات تمامًا كما يفعلون اليوم.

إليك سير عمل الاتصال. يمكنك أيضًا مراجعة وثائق GitHub حول ربط تطبيقات الطرف الثالث بالمستودعات إذا كنت غير متأكد من منح إذن OAuth.

1. في Apidog، أنشئ مشروعًا جديدًا بوضع Spec-First Mode.
2. صادق Apidog باستخدام حساب GitHub أو GitLab الخاص بك واختر المستودع.

3. عيّن الفرع (branch): استخدم فرعك الافتراضي (main أو master) لمواصفات الإنتاج، أو فرع ميزة (feature branch) أثناء اختبار الترحيل.

1. احفظ. يقرأ Apidog المواصفات ويبني التوثيق التفاعلي ونقاط نهاية الخادم الوهمي وهيكل الاختبار منها.

إذا كانت مواصفاتك تستخدم $ref لسحب المخططات من دليل models/، فإن Apidog يحل هذه المراجع نسبةً إلى موقع ملف المواصفات. لا حاجة إلى تكوين إضافي طالما أن المسارات في ملف OpenAPI الخاص بك صحيحة. للحصول على نظرة أعمق حول كيفية عمل مزامنة Git هذه، يغطي دليل مزامنة مواصفات OpenAPI مع GitHub الآليات بالتفصيل.

الخطوة 4: ترحيل وثائق Markdown الخاصة بك

يتيح لك Stoplight دمج صفحات دليل Markdown مع وثائق مرجع API في شريط جانبي واحد. يفعل Apidog الشيء نفسه من خلال محرر الوثائق الخاص به.

بعد ربط مستودعك، قم باستيراد ملفات Markdown من مجلد docs/:

1. في مشروع Apidog، افتح قسم Docs (الوثائق).
2. استخدم Import > Markdown (استيراد > Markdown) وقم بتحميل ملفاتك، أو الصق المحتوى صفحة بصفحة.

بالنسبة لأصول الصور المشار إليها في ملف Markdown الخاص بك (مجلد assets/images/ في تخطيط Stoplight النموذجي)، قم بتحميلها إلى مساحة تخزين ملفات Apidog وحدث مراجع ![alt](path) في كل صفحة. إذا كانت صورك مستضافة بالفعل على شبكة تسليم المحتوى (CDN) أو عنوان URL عام، فلا تحتاج إلى تغيير أي شيء.

الخطوة 5: استبدال خادم Stoplight الوهمي

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

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

بالنسبة لفريق اعتاد على تشغيل stoplight mock reference/your-api.yaml محليًا، فإن التحول هو أن مهندسي ضمان الجودة ومطوري الواجهة الأمامية يصلون الآن إلى عنوان URL سحابي مشترك بدلاً من ذلك. يستحق هذا الأمر التحقق منه في نسخة تجريبية للتأكد من أنه يتوافق مع سياسات الوصول إلى الشبكة الخاصة بك.

الخطوة 6: إعادة بناء مجموعات الاختبار الخاصة بك

إذا كنت تستخدم اختبار العقود من Stoplight أو قواعد Spectral للتحقق (linting)، فهذه تتطلب معالجة منفصلة.

قواعد التحقق (lint) لـ Spectral: يستخدم Stoplight Spectral للتحقق من توافق OpenAPI، ويتم تكوينه عبر ملف .spectral.yaml. يمتلك Apidog قواعد التحقق المدمجة الخاصة به للامتثال لـ OpenAPI، لكنه لا يشغل Spectral مباشرة. إذا كان لديك قواعد Spectral مخصصة يعتمد عليها فريقك، فاستمر في تشغيلها في التكامل المستمر (CI) (GitHub Actions أو GitLab CI) بشكل مستقل عن Apidog. إن تغطية Apidog للتحقق وما إذا كان يمكنك مشاركة مجموعات قواعد التحقق المخصصة عبر المشاريع يستحق التحقق منه في نسخة تجريبية مقابل متطلبات قواعدك المحددة.

اختبارات API: يتضمن Stoplight Platform اختبار API المستند إلى السيناريوهات. يتيح لك مشغل الاختبارات في Apidog بناء سيناريوهات الاختبار بصريًا، وربط الطلبات، وتشغيل التأكيدات ضد جسم الاستجابة، والرؤوس، وأكواد الحالة. ستقوم بإعادة بناء هذه الاختبارات داخل Apidog؛ لا يوجد استيراد تلقائي من مشاريع اختبار Stoplight. يوضح دليل سير عمل API الأصلي لـ Git كيفية دمج تشغيل اختبارات Apidog في مسار عمل GitHub Actions.

مثال عملي: إذا كان اختبار Stoplight الخاص بك قد تحقق من أن POST /orders يُعيد 201 مع رأس location، فإليك إعداد اختبار Apidog المكافئ في مسار عمل CI باستخدام واجهة سطر أوامر Apidog (CLI):

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

يحل هذا محل تشغيل اختبار Stoplight في CI ويحافظ على هيكل GitHub Actions الحالي الخاص بك سليمًا.

قائمة التحقق للتقييم لفرق المؤسسات

إذا كنت تقوم بالترحيل لفريق أكبر (النوع الذي يقوم بتقييم Stoplight Platform بدلاً من Studio)، فهناك قدرات محددة تستحق التحقق منها قبل الالتزام. يغطي Apidog هذه المجالات، ولكن السلوك الدقيق يعتمد على خطتك وتكوين مساحة العمل.

اعتبر هذه مهام تقييم، وليست عوائق. يمكن تأكيد معظمها في نسخة تجريبية مدتها أسبوعان باستخدام مشروع نموذجي.

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

هل يمكنني الاستمرار في استخدام Spectral مع Apidog؟

نعم. قم بتشغيل Spectral في مسار عمل CI الخاص بك بشكل مستقل عن Apidog. يبقى ملف .spectral.yaml الخاص بك في المستودع، ويقوم مهمة CI الخاصة بك (GitHub Actions، GitLab CI) بالتحقق من ملف OpenAPI عند كل طلب سحب (PR). يتعامل Apidog مع التوثيق والاختبارات الوهمية (mocking) والاختبار؛ ويتعامل Spectral مع التحقق (linting). لا يوجد تعارض بينهما. راجع وثائق Spectral لخيارات تكامل CI.

هل ستتعطل مسارات $ref الخاصة بي عند ربط المستودع بـ Apidog؟

ليس إذا كانت مساراتك صحيحة في ملف المواصفات. يحل Apidog $ref بالنسبة إلى موقع ملف OpenAPI الجذري. إذا كانت مواصفاتك تقول $ref: '../models/error.json' وكان مجلد models/ أعلى مستوى واحد من reference/، فإن Apidog يتبع هذا المسار النسبي في المستودع. اختبر بمواصفات تستخدم مراجع خارجية أولاً.

هل يدعم وضع Apidog Spec-First كلاً من GitLab وGitHub؟

نعم، كلاً من GitHub وGitLab مدعومان. سير عمل الاتصال هو نفسه؛ تقوم بالمصادقة باستخدام حساب GitLab الخاص بك وتحديد المستودع والفرع. لمزيد من المعلومات حول خيارات التحكم في الإصدار، يغطي دليل التحكم في إصدار OpenAPI باستخدام Git استراتيجيات الفروع بالتفصيل.

ماذا يحدث لعنوان URL لوثائق Stoplight الحالي بعد الترحيل؟

تتوقف عناوين URL لوثائق Stoplight المستضافة (docs.stoplight.io/your-org/your-api) عن العمل بمجرد إلغاء اشتراكك في Stoplight. يمنح Apidog وثائقك عنوان URL جديدًا على نطاق فرعي تقوم بتكوينه. قم بإعداد عمليات إعادة التوجيه على طبقة DNS أو CDN إذا كان لديك روابط خارجية تشير إلى صفحات وثائق Stoplight الخاصة بك.

هل أحتاج إلى حذف .stoplight.json و toc.json من المستودع؟

لا. يتجاهل Apidog الملفات التي لا يتعرف عليها. اتركها في مكانها إذا كان إزالتها ستسبب تعارضات دمج أو ارتباكًا. بمجرد أن ينتقل الفريق بالكامل إلى Apidog، يمكنك حذفها في طلب سحب للتنظيف، لكنه ليس مطلوبًا لكي يعمل الترحيل.

الخلاصة

الترحيل من Stoplight إلى Apidog لا يعني البدء من الصفر. تبقى مواصفات OpenAPI الخاصة بك في Git، ويبقى سير عمل الفروع الخاص بك سليمًا، ويتوافق هيكل الدليل الخاص بك reference/ و models/ و docs/ بشكل نظيف مع ما يتوقعه Apidog. الترحيل هو تبديل للإعدادات: استبدل .stoplight.json و toc.json بإعدادات مشروع Apidog، وقم بربط مستودعك عبر وضع Spec-First، وأعد بناء سيناريوهات الاختبار الخاصة بك داخل مشغل اختبار Apidog.

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