لقد فتحت طلب سحب (pull request)، وتم بناء الوثائق بشكل جيد، وبعد ثلاثة أيام، قام أحد زملائك بتنبيهك: يرفض خادم التطوير (staging server) كل طلب لأن ملف OpenAPI يحتوي على $ref معلق يشير إلى مسار قمت بتغيير اسمه. بدت المواصفات صحيحة في المحرر. وتم عرضها في Swagger UI. لكنها لم تكن صالحة فعليًا، ولم يكتشفها شيء في مسار عملك قبل نشرها.
هذه هي بالضبط الوظيفة التي صُممت من أجلها أداة Swagger سطر الأوامر: اكتشاف المواصفات المعطلة قبل أن يكتشفها البشر. عادةً ما تشير عبارة "swagger cli" إلى @apidevtools/swagger-cli، وهي حزمة npm صغيرة تتكون من أمرين، validate و bundle، للتحقق من مستند OpenAPI وربط المواصفات متعددة الملفات في ملف واحد. إنها أداة مفيدة حقًا، ويوضح لك هذا الدليل كيفية استخدامها بشكل صحيح. كما يوضح لك حدودها، لأن التحقق من المواصفات هو النصف الأول فقط من الوثوق بواجهة برمجة التطبيقات؛ النصف الثاني هو إرسال طلبات حقيقية والتأكد مما يعود، وهذا هو المكان الذي تتولى فيه أداة تشغيل مثل Apidog CLI المهمة.
إذن، هذا حقًا عمل يتطلب محطتين طرفيتين. أولاً، تحقق من المواصفات واجمعها باستخدام swagger-cli (أو خليفتها) بحيث يكون العقد سليمًا. ثم قم بتشغيل اختبارات فعلية على واجهة برمجة التطبيقات (API) قيد التشغيل من سطر الأوامر لتتأكد من أن التنفيذ يتطابق مع العقد. سنغطي كليهما، ونكون صريحين بشأن الأداة التي تمتلك أي وظيفة، ونقدم لك أوامر نسخ ولصق لكل منهما.
ما يشير إليه "swagger cli" فعليًا
لا يوجد برنامج تنفيذي رسمي واحد يسمى "swagger". يشير الاسم إلى عدد قليل من الأدوات المختلفة، ومعرفة أي منها تقصد يوفر الكثير من الالتباس.
@apidevtools/swagger-cliهي الحزمة التي يقصدها معظم الناس. برنامجها التنفيذي هوswagger-cli، ويقوم بشيئين: التحقق من صحة مستند OpenAPI أو Swagger 2.0، وجمع مواصفات متعددة الملفات في ملف واحد. وهو محور النصف الأول من هذا المقال.swagger-codegenهو مشروع SmartBear منفصل وأكبر بكثير يقوم بإنشاء حزم تطوير العميل (client SDKs) وكائنات خدمة الخادم (server stubs) من المواصفات. وظيفة مختلفة تمامًا؛ سنتطرق إليها في النهاية.- Swagger UI و Swagger Editor ليستا أدوات سطر أوامر على الإطلاق. إنهما يعرضان ويعدّلان المواصفات في المتصفح. إذا كنت لا تزال تتعلم التنسيق، فإن دليل Swagger و OpenAPI التمهيدي هو نقطة البداية الصحيحة.
يتعلق هذا الدليل بعمل سطر الأوامر: التحقق، التجميع، التدقيق، ثم الاختبار. إذا كنت تريد استعراضًا أوسع لمنصات التصميم والاختبار بدلاً من ذلك، فإن مجموعة بدائل Swagger تغطي جانب واجهة المستخدم الرسومية (GUI).
تثبيت swagger-cli
تأتي الأداة كحزمة npm. قم بتثبيتها عالميًا:
npm install -g @apidevtools/swagger-cli
تأكيد حلها:
swagger-cli --version
swagger-cli --help
يعتبر Node.js هو التبعية الوحيدة للنظام. يمكن لأي جهاز أو صورة CI مثبت عليها Node بالفعل تشغيلها. إذا كنت تفضل عدم تثبيتها عالميًا، يمكنك استدعاؤها عند الطلب باستخدام npx @apidevtools/swagger-cli ...، وهو أمر مفيد على أدوات بناء المرة الواحدة (ephemeral build runners).
شيء واحد يجب معرفته قبل الاعتماد عليها: لقد أشار القائمون على الصيانة إلى أن swagger-cli قد تم إهمالها. يشير ملف README إلى ذلك بوضوح، مستشهدًا بعبء صيانة قاعدة مستخدمين كبيرة مع عدد قليل من المساهمين. لا تزال تعمل، والعديد من مسارات العمل (pipelines) تشغلها اليوم، ولكن المشاريع الجديدة تُوجه إلى Redocly CLI كخلفٍ يتم صيانته بنشاط. سنغطي هذا الانتقال في قسم خاص به أدناه، حتى تتمكن من اتخاذ قرارك بوعي.
التحقق من المواصفات باستخدام swagger-cli
الأمر الرئيسي هو validate. وجهه إلى ملف المواصفات الخاص بك:
swagger-cli validate openapi.yaml
إذا كان المستند سليمًا، ستحصل على تأكيد من سطر واحد ورمز خروج 0. إذا كان هناك خطأ ما، فستحصل على رسالة خطأ تصف المشكلة ورمز خروج غير صفري، وهذا بالضبط ما تريده في مسار العمل (pipeline).
يقوم validate بتشغيل عمليتين فحصين تحت الغطاء، ويمكنك إيقاف أحدهما:
swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml
يتخطى --no-schema التحقق من صحة OpenAPI JSON Schema، وهو الفحص الهيكلي الذي يؤكد أن مستندك له الشكل الصحيح. يتخطى --no-spec التحقق من صحة قواعد المواصفات نفسها، وهو الفحص الدلالي الذي يكتشف أشياء مثل معرفات العمليات المكررة (duplicate operation IDs) أو $ref الذي لا يشير إلى أي مكان. في معظم الأوقات، تريد تشغيل كليهما، وهو الإعداد الافتراضي. توجد العلامات للحالات النادرة التي تشير فيها إحدى الطبقات إلى شيء لديك سبب متعمد للسماح به.
ما تكتشفه validate بشكل جيد: YAML مشوه، حقول إلزامية مفقودة، مؤشرات $ref مكسورة، وأخطاء هيكلية تجعل المواصفات غير قابلة للتحليل. ما لا تفعله هو فرض نمط فريقك. ستمرر المواصفات بسعادة بدون أوصاف، وتسميات غير متناسقة، ولا أمثلة، لأن لا شيء من ذلك يكسر قواعد OpenAPI. لهذا النوع من الفحص المحدد، تحتاج إلى مدقق نمط (linter)، وهو القسم التالي.
إذا كان التحقق هو الشيء الوحيد الذي جئت من أجله، فإن الشرح المتعمق حول كيفية التحقق من صحة مواصفات OpenAPI يقارن العديد من الأدوات والحالات الهامشية التي تستحق المعرفة.
تجميع المواصفات متعددة الملفات
نادراً ما تعيش المواصفات الحقيقية في ملف واحد. تقسم المخططات إلى دليل components/، وتشير إليها باستخدام $ref، وتحافظ على قابلية قراءة الملف الجذري. هذه ممارسة جيدة، ولكن العديد من الأدوات اللاحقة تريد مستندًا واحدًا مكتفٍ ذاتيًا. يقوم أمر bundle بتسطيح الشجرة:
swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml
العلامات التي تستحق المعرفة:
-o, --outfile <file>يكتب النتيجة إلى ملف بدلاً من طباعتها على المخرجات القياسية (stdout).-t, --type <json|yaml>يحدد تنسيق الإخراج. الافتراضي هوjson، لذا مرر-t yamlإذا كنت تريد إخراج YAML.-r, --dereferenceيقوم بتضمين كل$refبالكامل بدلاً من مجرد جمع الملفات الخارجية في مستند واحد. ينتج عن هذا ملف أكبر بدون أي مراجع متبقية، وهو ما تطلبه بعض الجهات المستهلكة.-f, --format <spaces>يتحكم في المسافات البادئة، الافتراضي هو مسافتين.-w, --wrap <column>يحدد طول السطر لالتفاف سلاسل YAML الطويلة.
التمييز بين التجميع العادي و --dereference مهم. يحافظ التجميع العادي على مؤشرات $ref الداخلية ولكنه يجمع جميع الملفات المنفصلة في ملف واحد، بحيث يكون المستند قابلاً للنقل. تقوم --dereference بحل كل مرجع إلى كائنات مضمنة، مما يزيد من حجم الملف ولكنه يضمن عدم اضطرار أي مستهلك على الإطلاق إلى حل مؤشر. استخدم التجميع العادي للتوزيع، والشكل الذي تم إلغاء مرجعيته فقط عندما تطلب أداة محددة ذلك.
نمط شائع هو التحقق والتجميع في خطوة واحدة كجزء من عملية البناء:
swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json
يعني الرمز && أن عملية التجميع لا تتم إلا إذا نجح التحقق، وبالتالي فإن المواصفات المعطلة لن تنتج أبدًا مُخرجات بناء.
ربط swagger-cli بنظام CI
يكون التحقق أكثر قيمة عندما يتم تشغيله مع كل تغيير، وليس عندما يتذكر شخص ما ذلك. أدرجه في مسار عملك كبوابة سريعة. إليك خطوة GitHub Actions تفشل عملية البناء عند وجود مواصفات غير صالحة:
name: Validate OpenAPI spec
on:
pull_request:
paths:
- 'openapi.yaml'
- 'components/**'
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Validate spec
run: npx @apidevtools/swagger-cli validate openapi.yaml
بما أن swagger-cli validate يخرج برمز غير صفري عند وجود مواصفات خاطئة، تتحول الخطوة إلى اللون الأحمر ويظهر طلب السحب (pull request) فحصًا فاشلاً. لا توجد إعدادات إضافية. يحافظ مرشح paths على عدم تشغيل المهمة عندما لا تتغير المواصفات، مما يقلل من دقائق CI الخاصة بك.
هذه هي أرخص بوابة جودة يمكنك إضافتها إلى مستودع API. تكلف ثوانٍ وتوقف فئة كاملة من أخطاء "الوثائق كاذبة" من الوصول إلى أي شخص في المراحل اللاحقة.
عندما تحتاج إلى التدقيق (linting) وليس فقط التحقق (validation)
يجيب التحقق على سؤال واحد: هل هذا مستند OpenAPI قانوني؟ يجيب التدقيق على سؤال أصعب: هل هذا مستند OpenAPI جيد وفقًا لمعايير فريقنا؟ ليسا متماثلين، و swagger-cli يقوم فقط بالأول.
لنفترض أن دليل أسلوبك يتطلب أن تحتوي كل عملية على summary، وكل خاصية على description، وكل مسار يستخدم kebab-case. يمكن للمواصفات أن تنتهك كل هذه الأمور وتظل تمرر swagger-cli validate، لأن أياً من هذه القواعد ليس جزءًا من مواصفات OpenAPI. يسمح لك المدقق (linter) بترميزها وفرضها.
هذا هو السبب الرئيسي وراء انتقال الفرق إلى Redocly CLI، وهو الخلف المدعوم الذي تشير إليه swagger-cli نفسها. إنه يغطي نفس عملية التحقق والتجميع، ثم يضيف محرك تدقيق حقيقي فوق ذلك.
الانتقال إلى Redocly CLI
الهجرة صغيرة لأن أسماء الأوامر متشابهة. قم بتثبيت الخلف:
npm install -g @redocly/cli
المكافئ للتحقق هو lint. لمطابقة السلوك القديم عن كثب، قم بتوسيع مجموعة القواعد الدنيا:
redocly lint --extends=minimal openapi.yaml
شغّله مع مجموعة القواعد الافتراضية بدلاً من ذلك، وسيقوم بفرض مجموعة أقوى من القواعد الموصى بها، وهو ما يظهر قيمة التدقيق (linting). يمكنك تكوين القواعد في ملف redocly.yaml، وتعيين كل منها إلى error أو warn، وحتى كتابة مكونات إضافية مخصصة لعمليات التحقق الخاصة بالمنظمة.
تتطابق عملية التجميع تقريبًا واحدًا لواحد:
redocly bundle openapi.yaml -o dist/openapi.yaml
تتغير أسماء العلامات قليلاً. تتحول -o/--outfile في swagger-cli إلى --output، و -t/--type إلى --ext، و -r/--dereference إلى -d/--dereferenced. إذا كانت نصوصك القديمة تستخدم العلامات القصيرة، فإن البحث والاستبدال السريع سيوصلك إلى هناك. للحصول على مقارنة أوسع لأدوات فحص المواصفات، فإن تفاصيل أفضل أدوات التحقق من صحة OpenAPI تضع Redocly بجانب البدائل.
النسخة المختصرة: إذا كنت تبدأ من جديد، فاستخدم Redocly CLI. إذا كانت لديك خطوة swagger-cli موجودة وتعمل، فلا توجد مشكلة فورية، ولكن المسار إلى الأمام واضح وإعادة التسمية ميكانيكية.
النصف الذي لا تستطيع أداة المواصفات تغطيته
هذا هو حد كل أداة ناقشناها حتى الآن. يؤكد swagger-cli validate أن مواصفاتك جيدة التكوين. يؤكد redocly lint أنها تتبع أسلوبك. لا ترسل أي منهما طلبًا واحدًا إلى واجهة برمجة التطبيقات (API) قيد التشغيل. يمكن أن تكون المواصفات مثالية على الورق بينما يعيد التنفيذ رمز 500، أو يحذف حقلًا وعد به، أو يتجاهل معلمة استعلام بالكامل.
سد هذه الفجوة يعني الاختبار الوظيفي: إرسال طلب حقيقي إلى نقطة نهاية حقيقية، ثم التحقق من رمز الحالة، وجسم الاستجابة، والقيم الموجودة فيه. هذه فئة مختلفة من الأدوات، وهذا هو المكان الذي يتناسب فيه Apidog مع سير العمل.
Apidog هي منصة API شاملة. تقوم باستيراد مواصفات OpenAPI الخاصة بك، ومن هذا التعريف الواحد تحصل على وثائق تفاعلية، وخادم وهمي (mock server)، وسيناريوهات اختبار يمكنك ربطها مع تأكيدات، كل ذلك دون مغادرة مساحة العمل. الاستيراد مباشر؛ دليل استيراد Swagger أو OpenAPI وإنشاء طلبات قابلة للتشغيل يشرح ذلك، ويمكنك إنشاء مجموعات اختبار كاملة مباشرة من المواصفات بدلاً من بنائها يدويًا.
الجزء المهم للمحطة الطرفية هو مشغل سطر الأوامر، المنشور كحزمة npm apidog-cli. تقوم بتثبيته وتشغيل سيناريو محفوظ بدون واجهة رسومية (headlessly):
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
علامة -t هي معرف سيناريو الاختبار، و -e هي معرف البيئة، و -r تختار تنسيقات التقارير مثل cli أو html أو json أو junit. مثل swagger-cli، فإنه يخرج برمز حالة نظيف، لذا فإن التأكيد الفاشل يحوّل مسار العمل إلى اللون الأحمر. على عكس swagger-cli، ما يتحقق منه هو السلوك المباشر لواجهة برمجة التطبيقات الخاصة بك، وليس فقط شكل الملف الذي يصفه. للحصول على مرجع كامل للعلامات وأمثلة CI، راجع دليل Apidog CLI الكامل، أو قم بتشغيل apidog run --help للحصول على الخيارات الحالية. إذا كنت ترغب في إعداد السيناريو الأول، قم بتنزيل Apidog، استورد مواصفاتك، وستجد أمر المشغل نسخة واحدة من علامة تبويب CI/CD للسيناريو.
سير عمل كامل من الطرفية
اجمع النصفين معًا وستحصل على مسار عمل يتحقق من العقد والتنفيذ بالتسلسل:
# 1. هل المواصفات جيدة التكوين ووفق النمط؟
redocly lint --extends=minimal openapi.yaml
# 2. إنتاج مستند واحد قابل للتوزيع.
redocly bundle openapi.yaml -o dist/openapi.yaml
# 3. هل تتطابق واجهة برمجة التطبيقات قيد التشغيل بالفعل مع العقد؟
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
الخطوة الأولى تفشل بسرعة عند وجود مواصفات مشوهة أو غير متوافقة مع النمط. الخطوة الثانية تنتج الارتفاق الذي تستهلكه وثائقك ومولدات SDK. الخطوة الثالثة ترسل حركة مرور حقيقية وتتحقق من الاستجابات، لذا فإن البناء الأخضر يعني أن كلاً من العقد والرمز خلفه سليمين. تخرج كل خطوة برمز غير صفري عند الفشل، لذا فإن السلسلة بأكملها هي بوابة واحدة يمكنك إسقاطها في أي مشغل CI يحتوي على Node.
إذا كان اختبارك اليوم يعتمد على أداة مطابقة المواصفات التي توقفت عن العمل، فإن المقال حول التحقق من واجهة برمجة التطبيقات مقابل مواصفاتها بدون Dredd يغطي نفس فكرة العقد مقابل التنفيذ من زاوية مختلفة.
ملاحظة حول swagger-codegen
الباحثون عن "swagger cli" قد يقصدون أحيانًا swagger-codegen، وهي أداة مختلفة بوظيفة مختلفة. تقرأ مواصفات OpenAPI وتنشئ حزم تطوير العميل (client SDKs)، وكائنات خدمة الخادم (server stubs)، والوثائق بعشرات اللغات. إنها مفيدة حقًا لبدء تشغيل عميل مكتوب (typed client) من مواصفات منشورة، ومن العدل وصفها بأنها الخيار الأكثر قدرة لتوليد الكود في عائلة Swagger.
لا تقوم بالتحقق، أو التدقيق (lint)، أو الاختبار بالمعنى الذي يغطيه هذا المقال. يفترض التوليد أن لديك بالفعل مواصفات سليمة؛ إذا كان الإدخال معطوبًا، فسيكون الإخراج معطوبًا بطرق مماثلة. لذلك حتى في سير عمل توليد الكود، لا تزال تريد خطوة تحقق أو تدقيق (lint) قبلها. تتكامل الأدوات مع بعضها البعض بدلاً من أن تحل إحداها محل الأخرى.