مواصفات OpenAPI هي عقد. تقرأها مولدات الكود، وتُبنى الوثائق منها، وتعمل الخوادم الوهمية عليها، ويتم إنتاج حزم SDK للعملاء منها. عندما تكون المواصفة خاطئة، يرث كل من هذه المنتجات النهائية الخطأ. يكتشف المدقق المشكلة في ملف المواصفات، قبل أن تنتشر.
تغطي هذه الجولة أدوات التحقق من OpenAPI التي تستحق الاستخدام، وما يميز كل واحدة منها، وكيف تتناسب مع سير عمل حقيقي. يتحقق بعضها من البنية الأساسية (syntax) الخام. بينما يفرض البعض الآخر قواعد النمط والتصميم. عادة ما يجمع أفضل إعداد بين الاثنين، ويشرح هذا الدليل كيفية تجميعه.
لماذا يُعد التحقق من المواصفات أمرًا مهمًا
هناك مشكلتان متميزتان تحلهما أداة التحقق، والخلط بينهما يسبب الالتباس.
الأول هو الصحة. هل الملف صحيح OpenAPI على الإطلاق؟ كتلة YAML بها خطأ في المسافة البادئة، أو $ref يشير إلى لا شيء، أو استجابة تفتقر إلى description المطلوبة، أو مخطط به خطأ إملائي في اسم النوع. هذه أخطاء موضوعية. الملف إما يحلل مقابل مخطط OpenAPI أو لا يحلل. يمنحك مدقق الصحة إجابة بنعم أو لا.
الثاني هو الجودة. المواصفة صالحة، ولكن هل هي جيدة؟ يجب أن تحتوي كل عملية على ملخص. يجب أن تكون أسماء المسارات متسقة. يجب توثيق كل استجابة خطأ. يجب الإعلان عن الأمان. لا شيء من هذه مطلوب بموجب مخطط OpenAPI، ولكن تخطيها ينتج مواصفة صالحة من الناحية الفنية ولكنها مؤلمة في الاستهلاك. تفرض أداة linter (مدقق الأنماط) قواعد التصميم هذه. اكتشاف كلا النوعين من المشكلات مبكرًا أرخص بكثير من اكتشافهما بعد شحن حزمة SDK، وهو نفس المنطق وراء اختبار عقد API بشكل أوسع.
أدوات التحقق التي تستحق المعرفة
محرر Swagger
محرر Swagger هو المحرر الرسمي القائم على المتصفح من مشروع OpenAPI. يمكنك لصق أو كتابة مواصفاتك على اليسار ورؤية أخطاء التحقق ومعاينة معروضة على اليمين، مباشرة. إنها أسرع طريقة للتحقق مما إذا كانت المواصفات صالحة من الناحية النحوية، وبدون أي إعداد. إنه ممتاز للتحرير والفحوصات السريعة، وأقل ملاءمة لتشغيل مسارات الأتمتة. محرر Swagger مجاني ويعمل بالكامل في المتصفح.
سبكترال (Spectral)
Spectral، من Stoplight، هو أداة التحقق من الأنماط (linter) التي تعتمدها معظم الفرق لفرض الجودة. يأتي مع مجموعات قواعد لـ OpenAPI و AsyncAPI، والقيمة الحقيقية تكمن في القواعد المخصصة. يمكنك كتابة القواعد بلغة YAML أو JavaScript لفرض اصطلاحاتك الخاصة، مثل طلب أن تحتوي كل عملية على وصف أو حظر الشرطات المائلة في نهاية المسارات. يعمل من سطر الأوامر، مما يجعله مناسبًا بشكل طبيعي لـ CI. مشروع Spectral مفتوح المصدر.
openapi-spec-validator
openapi-spec-validator هي أداة بايثون مركزة تقوم بمهمة واحدة بشكل جيد: تتحقق من المواصفات مقابل مخطط OpenAPI الرسمي للإصدارات 2.0 و 3.0 و 3.1. ليس لديها رأي حول الأنماط. تخبرك ما إذا كان الملف صحيحًا من الناحية الهيكلية. كمكتبة أو أداة سطر أوامر (CLI)، تتناسب بسلاسة مع خطوات البناء القائمة على بايثون وخطافات ما قبل الالتزام (pre-commit hooks). عندما تريد بوابة تحقق صارمة للنجاح أو الفشل، فهذا خيار نظيف.
أبيدوج (Apidog)
Apidog يتحقق من المواصفات كجزء من سير عمل تصميم متكامل. أثناء قيامك بإنشاء أو استيراد تعريف OpenAPI، فإنه يشير إلى المشاكل الهيكلية في المحرر. ميزته الأكثر تميزًا هي التحقق في وقت التشغيل (runtime validation): حيث يتحقق من استجابات API المباشرة مقابل المخطط المعلن في مواصفاتك، بحيث تكتشف الانحراف حيث لم يعد التنفيذ يطابق العقد. وهذا يسد الفجوة بين مستند صالح وواجهة برمجة تطبيقات صحيحة. قم بتنزيل Apidog لتصميم والتحقق من المواصفات في أداة واحدة.
واجهة سطر الأوامر Redocly (Redocly CLI)
تجمع Redocly CLI بين فحص الأنماط (linting) والتحقق وتوليد الوثائق. إنها تتحقق من صحة المخطط مقابل مخطط OpenAPI، وتأتي مع مجموعة قواعد قابلة للتكوين، ويمكنها دمج المواصفات متعددة الملفات في حزمة واحدة. تحصل الفرق التي تعرض الوثائق بالفعل باستخدام Redoc على التحقق في نفس سلسلة الأدوات دون إضافة تبعية أخرى.
فاكيوم (Vacuum)
Vacuum هي أداة فحص سريعة لمواصفات OpenAPI مكتوبة بلغة Go. نقطة قوتها هي السرعة في التعامل مع المواصفات الكبيرة جدًا، حيث تتباطأ بعض أدوات فحص الأنماط المعتمدة على JavaScript. إنها متوافقة مع قواعد نمط Spectral، لذا يمكن للفريق التبديل إليها بجهد قليل. بالنسبة لمستودع مشاريع أحادي (monorepo) مع سطح API واسع الانتشار، يكون فرق الأداء ملحوظًا.
جدول المقارنة
| الأداة | النوع | الفحوصات | يعمل في CI | الأفضل لـ |
|---|---|---|---|---|
| Swagger Editor | محرر متصفح | بنية نحوية، مخطط | لا | تحرير مباشر وفحوصات سريعة |
| Spectral | مدقق أنماط CLI | نمط، قواعد مخصصة | نعم | فرض اصطلاحات التصميم |
| openapi-spec-validator | CLI / مكتبة بايثون | صحة المخطط | نعم | بوابة نجاح أو فشل صارمة |
| Apidog | منصة متكاملة | مخطط + انحراف وقت التشغيل | نعم | تصميم بالإضافة إلى التحقق من الاستجابة |
| Redocly CLI | CLI | مخطط، نمط، تجميع | نعم | وثائق وتحقق معًا |
| Vacuum | مدقق أنماط CLI | نمط، قواعد Spectral | نعم | مواصفات كبيرة جدًا، سرعة |
كيفية تجميع سير عمل للتحقق
لا تختار أداة واحدة. بل تقوم بتركيبها طبقات فوق بعضها.
ابدأ من حيث تقوم بالتحرير. أثناء كتابة مواصفات، استخدم محرر Swagger أو منصة متكاملة بحيث تظهر الأخطاء أثناء الكتابة. هذا يكتشف الأخطاء الواضحة فورًا وهو أرخص بكثير من اكتشافها لاحقًا.
أضف بوابة صحة في CI. قم بتشغيل openapi-spec-validator أو ما يعادله من CLI على كل طلب سحب (pull request) يمس المواصفات. إذا لم يتم التحقق من صحة الملف مقابل مخطط OpenAPI، يفشل البناء. هذا غير قابل للتفاوض ومحدد بنعم أو لا.
أضف بوابة جودة بجانبها. قم بتشغيل Spectral، أو Vacuum للمواصفات الكبيرة، مع مجموعة قواعد يتفق عليها فريقك. ابدأ بقواعد OpenAPI المضمنة، ثم أضف قواعد مخصصة لاصطلاحاتك الخاصة. احتفظ بمجموعة القواعد في نظام التحكم في الإصدارات بحيث تتطور مع API. هذا هو نفس الانضباط الذي يجعل أتمتة الاختبارات في CI/CD موثوقة: يتم تشغيل الفحص في كل مرة، وليس عندما يتذكر أحدهم.
أخيرًا، تحقق من API قيد التشغيل مقابل المواصفات. يمكن أن تكون المواصفات مثالية بينما يكون التنفيذ قد انحرف عنها. التحقق في وقت التشغيل، سواء من خلال Apidog أو اختبارات العقد في مجموعتك، يؤكد أن API لا يزال يطابق عقده. بالنسبة لجانب الاختبار، تغطية تأكيدات API المفيدة توضح كيفية التحقق من الاستجابات مقابل المخطط الموثق.
خطأ شائع: التحقق لمرة واحدة
تقوم العديد من الفرق بالتحقق من المواصفات مرة واحدة، عندما يكتبونها لأول مرة، ثم لا يقومون بذلك مرة أخرى أبدًا. تتعفن المواصفات من هناك. يضيف مطور نقطة نهاية في الكود وينسى المواصفات. يقوم شخص ما بتعديل شكل الاستجابة. بعد ستة أشهر، تصف المواصفات API لم يعد موجودًا، وتكون حزم SDK والوثائق المُولدة خاطئة بصمت.
يجب أن يكون التحقق مستمرًا. قم بدمجه في CI بحيث يتم فحص كل تغيير في المواصفات، ويتم فحص كل تغيير في API مقابل المواصفات. تعامل مع فشل المواصفات بنفس الطريقة التي تتعامل بها مع اختبار وحدة فاشل: لا يمر البناء. المبدأ هو نفسه الذي يقف وراء الاختبار الآلي بشكل عام، وهو أن الفحص يكون ذا قيمة فقط إذا تم تشغيله دون أن يقرر أحد تشغيله.
يساعد أيضًا التحقق مقابل إصدار OpenAPI الصحيح. لقد قام إصدار 3.1 بمواءمة OpenAPI مع JSON Schema، مما غير كيفية تصرف بعض هياكل المخطط. إذا كانت أدواتك تفترض الإصدار 3.0 ولكن مواصفاتك تعلن عن 3.1، فقد تحصل على نتائج مضللة. مواصفات OpenAPI الرسمية توثق اختلافات الإصدارات، وتسمح لك معظم أدوات التحقق بتحديد الإصدار بشكل صريح.
ما تكتشفه أدوات التحقق مما قد يفوتك
من الجدير أن نكون محددين بشأن أنواع المشكلات التي تظهرها عملية التحقق، لأن عبارة "المواصفات خاطئة" غامضة جدًا بحيث لا يمكن التصرف بناءً عليها.
الأخطاء الهيكلية هي الأسهل في التخيل. $ref يشير إلى مخطط غير موجود. كائن استجابة بدون description، وهو ما تتطلبه OpenAPI. معامل مسار (path parameter) مُعلن في قالب URL ولكن لم يتم تعريفه أبدًا في قائمة parameters. مخطط يقول type: integer بينما يظهر المثال سلسلة نصية (string). يقوم مدقق الصحة بتمييز كل واحدة من هذه الأخطاء، وإلا فإن كل منها سيتسبب في كسر مولد الأكواد أو إنتاج حزمة SDK معيبة.
مشكلات الجودة أكثر دقة وأكثر شيوعًا. عملية بدون operationId، مما يجعل أسماء أساليب العميل (client method names) المولدة قبيحة أو غير مستقرة. حالة حروف المسار غير متسقة، حيث تستخدم بعض المسارات snake_case ويستخدم البعض الآخر camelCase. نقاط نهاية توثق استجابة 200 ولكن لا توثق أبدًا 400 أو 401، لذلك لا يملك المستهلكون فكرة عن شكل الأخطاء. نص طلب (request body) معلم اختياريًا بينما تتطلبه API فعليًا. لا شيء من هذه يكسر المحلل اللغوي (parser)، ولكن جميعها تجعل استخدام API أكثر صعوبة، ومدقق الأنماط (linter) هو ما يحافظ على الخط. الاتصال بالسلوك الحقيقي هو ما يتحقق منه اختبار عقد API بمجرد أن تصبح المواصفات نفسها نظيفة.
دمج التحقق في سير عمل "التصميم أولاً"
تقوم العديد من الفرق الآن بتصميم API قبل كتابة الكود، حيث تنتج مواصفات OpenAPI أولاً وتولد منها نُسخًا احتياطية للخوادم (server stubs)، ونماذج وهمية (mocks)، ووثائق. يصبح التحقق أكثر أهمية في هذا النموذج، لأن المواصفات ليست وثيقة لـ API موجودة؛ بل هي مصدر الحقيقة الذي يُبنى عليه كل شيء آخر. أي عيب في المواصفات يصبح عيبًا في الخادم المُولد.
في سير عمل "التصميم أولاً"، تحقق في لحظة التصميم. تكتشف الفحوصات على مستوى المحرر الأخطاء أثناء تشكل المواصفات، قبل تشغيل أي عملية لتوليد الكود. ثم تؤكد بوابات CI أنه لم يحدث أي تراجع. ولأن المواصفات تدفع الخادم الوهمي أيضًا، فإن المواصفات النظيفة تعني أن النموذج الوهمي يتصرف بشكل صحيح، مما يسمح لفرق الواجهة الأمامية والعميل بالبناء مقابل بديل موثوق به. إذا كنت ترغب في رؤية كيف تغذي المواصفات عملية إنشاء النماذج الوهمية، فإن دليلنا حول إنشاء نموذج وهمي لـ API للاختبار يوضح العلاقة. هذا الانضباط يؤتي ثماره: كل ساعة تقضيها في الحفاظ على صلاحية المواصفات توفر عدة ساعات من تصحيح أخطاء العملاء غير المتطابقين لاحقًا.
الأسئلة الشائعة
ما الفرق بين مدقق OpenAPI ومدقق الأنماط (linter)؟
يتحقق المدقق مما إذا كانت المواصفات صحيحة هيكليًا مقابل مخطط OpenAPI، مما يعطي إجابة بالنجاح أو الفشل. يتحقق مدقق الأنماط (linter) من الجودة والأسلوب، مثل ما إذا كانت كل عملية تحتوي على وصف أو ما إذا كانت تسمية المسارات متسقة. تقوم العديد من الأدوات بالوظيفتين، لكنها تجيب على أسئلة مختلفة، وسير العمل القوي يستخدم كليهما.
هل يمكنني التحقق من مواصفات OpenAPI مجانًا؟
نعم. كل من Swagger Editor و Spectral و openapi-spec-validator و Redocly CLI و Vacuum مجانية ومفتوحة المصدر. تتحقق Apidog من المواصفات في طبقتها المجانية وتضيف فحوصات وقت التشغيل. لا يوجد سبب لتخطي التحقق لأسباب تتعلق بالتكلفة.
هل يجب أن أتحقق من OpenAPI 3.0 و 3.1 بشكل مختلف؟
تتحقق منها بنفس الأدوات، ولكن قم بتحديد الإصدار. لقد تواءمت OpenAPI 3.1 مع JSON Schema وغيرت بعض سلوكيات المخطط، لذلك قد يُبلغ مدقق يتوقع 3.0 عن أخطاء خاطئة على مواصفات 3.1. تأكد من أن أدواتك تدعم الإصدار الذي تعلنه مواصفاتك.
أين يجب تشغيل التحقق من المواصفات؟
في مكانين. مباشرة في محرر النصوص الخاص بك أثناء كتابة المواصفات، بحيث تظهر الأخطاء فورًا، وفي CI على كل طلب سحب، حتى لا يتم دمج أي شيء بمواصفات معيبة أو ذات جودة منخفضة. التحقق من المحرر فقط سهل التجاوز؛ أما التحقق في CI فليس كذلك.
كيف أتحقق من أن API الخاص بي يطابق مواصفاته؟
يتحقق من صحة المواصفات فقط يؤكد أن المستند صحيح، وليس أن التنفيذ يطابقه. لاكتشاف الانحراف، قم بتشغيل اختبارات العقد أو التحقق في وقت التشغيل الذي يقارن استجابات API المباشرة بالمخطط في المواصفات. يقوم Apidog بذلك مباشرة، وتقوم أطر عمل اختبارات العقد بذلك في مجموعة اختبار.