كيفية الترحيل من Swagger CLI إلى Apidog CLI

إذا كنت لا تزال تشغل swagger-cli validate و swagger-cli bundle في مسار عملك، فأنت تحافظ على نص برمجي حول أداة لم يعد أحد يدعمها. يقول مستودع swagger-cli على GitHub الآن ذلك مباشرة: لم تعد الحزمة مدعومة، ويذكر ملف README عبء مواكبة قاعدة مستخدمين ضخمة لا تساهم كثيرًا، ويشير إلى المستخدمين الجدد إلى أماكن أخرى.

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

قم بتنزيل Apidog إذا كنت ترغب في المتابعة باستخدام الأوامر الحقيقية. البدء مجاني، ولا تتطلب بطاقة ائتمان.

button

لماذا تهاجر الآن

الإجابة الصادقة أولاً: تم إهمال swagger-cli وعدم صيانته لبعض الوقت. لا يزال يعمل. الكثير من مسارات العمل تستدعيه اليوم. لكن الأداة التي لن تحصل على إصلاحات للأخطاء أو تحديثات للمواصفات هي دين تقني موجود في نسختك، والمطورون أنفسهم يوصون بالانتقال.

يشيرون إلى خليفة واحد على وجه الخصوص. Redocly CLI هو البديل الأقرب والمباشر إذا كان كل ما أردته هو التحقق والتجميع في الطرفية. إنه مفتوح المصدر، يعتمد على الكود أولاً، ويتوافق مع الطرفية. يقوم أمر lint الخاص به بالتحقق الهيكلي، ويتبع redocly bundle مؤشرات $ref تمامًا كما فعل swagger-cli bundle. إذا كان هدفك الوحيد هو تبديل 1:1 يحافظ على المواصفات كملف واحد في المستودع الخاص بك، فإن Redocly هو الخيار الطبيعي، وينشر Redocly دليل الترحيل الخاص به مع تخطيط الأوامر. لا عيب في اتباع هذا المسار.

Apidog له هدف مختلف. انتقل إلى Apidog CLI عندما تريد أن تفعل المواصفات أكثر من مجرد الجلوس في ملف. بدلاً من التحقق من مستند ثابت وجمعه، يمكنك إحضار التعريف بالكامل إلى مساحة عمل حية، ثم التحقق منه عند الاستيراد، وتصدير ملف موحد عندما تحتاج إليه، واختيارياً محاكاة واجهة برمجة التطبيقات، وتشغيل سيناريوهات الاختبار عليها، ونشر المستندات من نفس المصدر. كان swagger-cli يفعل شيئين فقط. Apidog يغطي بقية دورة الحياة.

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

ماذا فعل swagger-cli مقابل ما يفعله Apidog CLI

كان لدى swagger-cli أمران بالضبط:

قام swagger-cli validate <file> بفحص مستند Swagger 2.0 أو OpenAPI 3.0 مقابل المخطط وتحقق من حل مؤشراته $ref.
قام swagger-cli bundle <file> بمتابعة مؤشرات $ref هذه ودمج تعريف متعدد الملفات في ملف واحد، مع خيارات لمسار الإخراج (-o)، والنوع (-t json|yaml)، وإزالة الإشارة الكاملة (-r)، والمسافة البادئة (-f).

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

يقوم Apidog CLI بتعيين هاتين الوظيفتين على اثنين من أوامره، ثم يواصل:

يستقبل apidog import تعريفًا في مشروع Apidog ويتحقق منه أثناء الإدخال. يتم حل مؤشرات $ref للمواصفات متعددة الملفات في موارد موحدة تلقائيًا. هذه هي خطوة التحقق الخاصة بك، بالإضافة إلى الاستقبال.
يُصدر apidog export ملفًا موحدًا واحدًا من المشروع، ويتيح لك اختيار إصدار OpenAPI عند الإخراج. هذه هي خطوة التجميع الخاصة بك، بالإضافة إلى ترقية اختيارية للإصدار والقدرة على إصدار مستندات HTML أو Markdown.
يُنفذ apidog run سيناريوهات ومجموعات الاختبار، مع تقارير JUnit وغيرها لـ CI. لم يكن لدى swagger-cli ما يعادله.
تُدير أوامر الموارد (endpoint، schema، mock، environment، branch، والمزيد) المشروع من الطرفية بمجرد إدخال المواصفات.

نقطة دقيقة واحدة للحفاظ على صدق التعيين: يتحقق Apidog من البنية عند الاستيراد، ولكنه ليس أداة فحص قابلة للتكوين لقواعد النمط. لا يوجد apidog lint ولا مجموعات قواعد مخصصة. إذا كنت تعتمد على الفحص المتعمد، فإن هذا الجزء لا ينتقل، ويغطي قسم ما الذي تكسبه أبعد من التحقق والتجميع كيفية التعامل مع ذلك.

التثبيت وتسجيل الدخول

يتم شحن Apidog CLI كحزمة npm. قم بتثبيتها عالميًا:

npm install -g apidog-cli@latest

ثم قم بالمصادقة باستخدام رمز وصول:

apidog login --with-token <TOKEN>

يمكنك الحصول على الرمز المميز من تطبيق Apidog أو الويب: انقر على صورتك الرمزية، انتقل إلى Account Settings (إعدادات الحساب)، ثم API Access Token (رمز وصول API)، وقم بإنشاء واحد. يخزن واجهة سطر الأوامر (CLI) الرمز المميز في ~/.apidog/config.toml. تعامل معه كأي سر آخر. لا تطبعه في السجلات أو تلتزم به في مستودعك.

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

جدول تعيين الأوامر

إليك الترجمة المباشرة من swagger-cli إلى Apidog CLI. الاختلاف الهيكلي الوحيد: يعمل Apidog على مشروع، لذا فإن معظم التدفقات هي استيراد ثم تصدير بدلاً من أمر واحد على ملف غير مقيد.

أمر swagger-cli	المكافئ في Apidog CLI	ما يتغير
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	يتم التحقق من المواصفات عند الاستيراد؛ المواصفات غير الصالحة تفشل الأمر
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` ثم `apidog export --project <id> --format openapi --output ./out.json`	يصبح التجميع تصديرًا من المشروع؛ تم حل `$refs` بالفعل عند الاستيراد
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	يتبع تنسيق الإخراج الملف الذي تكتبه
(لا يوجد مكافئ)	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	ترقية مواصفات 2.0 أو 3.0 إلى 3.1 عند التصدير
(لا يوجد مكافئ)	`apidog export --project <id> --format html --output ./docs.html`	إصدار وثائق HTML مستقلة
(لا يوجد مكافئ)	`apidog export --project <id> --format markdown --output ./docs.md`	إصدار وثائق Markdown
(لا يوجد مكافئ)	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	تشغيل اختبارات API في CI

الخليتان الأكثر أهمية للترحيل هما الصفان الأولان. كل ما يليهما هو قدرات لم يكن يمتلكها swagger-cli أبدًا. تعد علامة --oas-version هي الترقية الأكثر وضوحًا: كان swagger-cli قادرًا على تجميع ملف Swagger 2.0، لكنه لم يتمكن من تحويله إلى OpenAPI 3.1. يمكن لـ Apidog فعل ذلك عند التصدير، وهو أمر مفيد عندما تقوم بتحديث عقد قديم. إذا كان هدفك هو إخراج المستندات تحديدًا، فإن تصدير OpenAPI إلى Markdown يتناول هذا التنسيق بعمق أكبر.

الترحيل خطوة بخطوة

إليك المسار الكامل من إعداد swagger-cli إلى سير عمل Apidog فعال.

1. احصل على معرف مشروعك. أنشئ أو افتح مشروعًا في تطبيق Apidog. يظهر معرف المشروع في إعدادات المشروع وفي عنوان URL. ستقوم بتمريره إلى كل أمر CLI عبر --project.

2. استورد المواصفات الجذرية. وجّه Apidog إلى ملف إدخال تعريفك. يتم حل المواصفات متعددة الملفات مع مؤشرات $ref تلقائيًا، لذا يمكنك استيراد الجذر ويسحب Apidog البقية:

apidog import --project 123456 --format openapi --file ./openapi.yaml

إذا كانت المواصفات مشوهة أو كان هناك $ref معلق، يفشل الاستيراد. هذا الفشل هو بوابة التحقق الخاصة بك، وهي نفس الوظيفة التي كان يقوم بها swagger-cli validate، وقد تم دمجها الآن في عملية الاستيعاب.

3. تحقق في التطبيق. افتح المشروع وتأكد من أن نقاط النهاية والمخططات والمعلمات قد وصلت بشكل صحيح. هذا الفحص البصري لا يوجد له مكافئ في swagger-cli، ويستحق القيام به مرة واحدة أثناء الترحيل للتأكد من أن الاستيراد قد أدى ما توقعته.

4. تصدير الملف الموحد. عندما تحتاج إلى ملف واحد مسطح (لأداة لاحقة، أو منشئ عميل، أو عنصر)، قم بتصديره. اختر إصدار OpenAPI الذي تريده:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

هذا يحل محل swagger-cli bundle. تم حل مؤشرات $ref بالفعل عند الاستيراد، لذا فإن التصدير هو إخراجك الموحد في ملف واحد.

5. ربطها بـ CI. استبدل خطوة swagger-cli القديمة بالاستيراد (التحقق عند الاستيعاب) والتصدير (التجميع)، وأضف تشغيل اختبار إذا كان لديك سيناريوهات. القسم التالي يحتوي على مثال كامل لـ GitHub Actions.

مثال CI مع GitHub Actions

يقوم سير العمل هذا بتثبيت واجهة سطر الأوامر (CLI)، وتسجيل الدخول باستخدام رمز من أسرار المستودع، واستيراد المواصفات للتحقق منها، وتصدير قطعة أثرية مدمجة، ثم تشغيل سيناريوهات الاختبار باستخدام مُبلغ JUnit بحيث يفشل الاختبار الفاشل في الفحص ويحجب طلب السحب.

name: API spec check

on:
  pull_request:
    branches: [main]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

قم بتخزين الرمز المميز باسم APIDOG_ACCESS_TOKEN في أسرار مستودعك حتى لا يظهر أبدًا في السجلات. يقوم مُبلغ -r "cli,junit" بكتابة ملف XML من نوع JUnit يمكن أن تعرضه CI كتقرير اختبار، ويعيد السيناريو الفاشل رمز خروج غير صفري يمنع الدمج. لأنماط مسار العمل الأعمق، راجع دليل Apidog CLI CI/CD، ولإعدادات مُشغل معينة، راجع مراجعة Apidog CLI مع GitHub Actions.

ما الذي تكسبه أبعد من التحقق والتجميع

هنا تظهر فائدة الترحيل، وهنا تكمن أهمية الصدق.

خوادم وهمية. بمجرد أن تكون مواصفاتك في مشروع، يمكن لـ Apidog تقديم استجابات وهمية منها. يمكنك تطوير واجهة أمامية مقابل واجهة برمجة التطبيقات قبل وجود الواجهة الخلفية. لم يمس swagger-cli سلوك وقت التشغيل أبدًا.

سيناريوهات الاختبار الآلي. ينفذ apidog run طلبات حقيقية مقابل واجهة برمجة تطبيقات قيد التشغيل ويؤكد على الاستجابات. يمكنك بناء سيناريوهات بصريًا في التطبيق، ثم تشغيلها بلا رأس في CI. هذا يسد الفجوة التي تركها swagger-cli مفتوحة على مصراعيها: المواصفات الصالحة تخبرك بأن العقد جيد التكوين، وليس أن التنفيذ يطابقه.

وثائق مستضافة ومصدرة. apidog export --format html أو --format markdown ينتج وثائق مباشرة من نفس المصدر. لا توجد خطوة بناء وثائق منفصلة للصيانة.

الآن، الحد الصادق. لا يحتوي Apidog CLI على مدقق نمط قابل للتكوين، يعتمد على الكود أولاً، مع مجموعات قواعد مخصصة. يتحقق من البنية عند الاستيراد، ولكن لا يمكنك تأليف قواعد على غرار Spectral أو Redocly عبر CLI، ولا يوجد أمر apidog lint. إذا كان إعدادك القديم يعتمد على الفحص الثقيل (تسمية متسقة، وصف مطلوب، أمثلة على كل استجابة)، فاحتفظ بمدقق مخصص في الحلقة. قم بإقران Apidog بـ Spectral أو Redocly لذلك، وقم بتشغيله كخطوة CI منفصلة. يغطي دليل إعداد مدقق OpenAPI كيفية ربط واحد. استخدام كلاهما ليس تناقضًا: قم بالتحقق باستخدام أداة متخصصة، ثم قم بإدارة دورة الحياة في Apidog.

button