ملف Swagger التالف نادرًا ما يُعلن عن نفسه. يتم تحليل YAML بشكل جيد. صفحة التوثيق تُعرض. ثم يقوم مطور واجهة أمامية بإنشاء عميل من مواصفاتك، ويفشل البناء بسبب حقل required مفقود، وتكتشف أن وصف واجهة برمجة التطبيقات "المنتهي" الخاص بك كان به خطأ إملائي في $ref قبل ثلاث تثبيتات. كانت المواصفات خاطئة طوال الوقت. لم يخبرك شيء بذلك حتى كلف أحدهم بعد ظهر يوم كامل.
هذه هي وظيفة مدقق Swagger: يقرأ ملف OpenAPI أو Swagger الخاص بك ويخبرك، قبل أن يستهلكه أي شخص، ما إذا كان المستند صالحًا بالفعل. ليس "هل يبدو صحيحًا"، بل "هل يتوافق مع مواصفات OpenAPI، ويحل كل مرجع، ويصف مخططًا يمكن للأداة الوثوق به". يحول المدقق الأخطاء الهيكلية الصامتة إلى أخطاء صاخبة ومرقمة بالسطور يمكنك إصلاحها في ثوانٍ بدلاً من تصحيح الأخطاء لاحقًا لساعات.
ماذا يتحقق مدقق Swagger فعليًا
أولاً، التسمية. يصف "Swagger" و"OpenAPI" نفس الشيء في نقاط مختلفة من التاريخ. كان التنسيق يُسمى Swagger حتى الإصدار 2.0، ثم تم التبرع به لمبادرة OpenAPI وأعيد تسميته؛ الإصدارات 3.0 و 3.1 و 3.2 كلها OpenAPI. لا يزال الناس يقولون "مدقق swagger" من باب العادة، وتقبل معظم الأدوات كلاً من Swagger 2.0 و OpenAPI 3.x. إذا كان تاريخ الإصدار غامضًا، فإن التفصيل بين Swagger و OpenAPI يوضحه. للاطلاع على الاختلافات بين الإصدارات الحديثة، انظر ما تغير في OpenAPI 3.2 مقابل 3.1 مقابل 3.0.
يقوم المدقق الحقيقي بثلاث مهام، بالترتيب:
- التحليل. هل الملف صالح حتى كـ YAML أو JSON؟ علامة تبويب خاطئة، مفتاح مكرر، قوس غير مغلق، المستند لا يُحمّل أبدًا. هذا هو أرخص خطأ يمكن اكتشافه والأكثر إحراجًا عند النشر.
- التحقق من الهيكل. هل المستند يتوافق مع مخطط OpenAPI؟ كل عملية تحتاج إلى كائن
responses. كل معلمة تحتاج إلى قيمةin. يجب أن يشير$refإلى شيء موجود. هذا هو المكان الذي تختبئ فيه معظم الأخطاء الحقيقية. - حل المراجع. مستندات OpenAPI مليئة بمؤشرات
$refالتي تربط المخططات القابلة لإعادة الاستخدام معًا. يتبع المدقق كل واحد ويفشل إذا كان الهدف مفقودًا، أو دائريًا بطريقة تحظرها المواصفات، أو يشير إلى ملف خاطئ.
اجتياز هذه الثلاثة يعني أن لديك مستندًا يمكن لأي أداة متوافقة، أو مولد أكواد، أو خادم وهمي، أو عارض مستندات، قراءته دون تعثر. فشل أي منها يظهر الفشل في مكان أقل ملاءمة من محطتك الطرفية.
الأخطاء التي يكتشفها والتي تظهر لاحقًا
يبدو التحقق أمرًا مجردًا حتى ترى ما يتسرب بدونه. هذه هي أخطاء المواصفات التي تبدو غير ضارة في المحرر وتتحول إلى حوادث حقيقية لاحقًا.
مؤشرات $ref المعطلة. تقوم بإعادة تسمية مخطط من User إلى UserProfile ولكنك تفوت مرجعًا واحدًا عميقًا في جسم الاستجابة. لا يزال YAML يُحلل. لا تزال المستندات تُعرض بقية الصفحة. يصل مولد الأكواد إلى المؤشر المعلق ويصدر عميلاً بنوع مفقود، أو يتعطل ببساطة. يعلم المدقق عن $ref المعطل في لحظة الحفظ.
عدم تطابق المخطط والمثال. يقول المخطط الخاص بك إن age هو عدد صحيح؛ بينما يظهر مثالك "age": "thirty". يعرض Swagger UI كلاهما بسعادة. ثم يعيد خادم وهمي تم بناؤه من المواصفات سلسلة نصية حيث يتوقع المستهلكون رقمًا، ويتحول اختبار العقد لثلاثة فرق إلى اللون الأحمر لأسباب لا يمكن لأحد تتبعها إلى ملفك.
الأجزاء المطلوبة المفقودة. عملية بدون responses. معلمة مسار مُعلن عنها في قالب URL ولكن لم يتم تعريفها أبدًا في parameters. requestBody بدون content. كل منها يعتبر تقنيًا مستندًا مشوهًا، وكل منها ينتج عرضًا مختلفًا لاحقًا اعتمادًا على الأداة التي تقرأ المواصفات أولاً.
اختلاف النوع والتنسيق. format: date-time على حقل يعيده الواجهة الخلفية (backend) كتوقيت Unix. type: string على شيء هو في الواقع مصفوفة. هذه تمر بالتحقق الهيكلي ولكنها تكسر العقد بين المواصفات وواجهة برمجة التطبيقات (API) قيد التشغيل، وهي مشكلة منفصلة سنتناولها.
النمط ثابت: خطأ في المواصفات يكون غير مرئي في اللحظة التي ترتكبه فيها ومكلف في اللحظة التي يستهلكه فيها شخص آخر. ينقل التحقق التكلفة إلى حيث تكون رخيصة.
كيفية التحقق من ملف Swagger يدويًا
لا تحتاج إلى منصة للبدء. هناك ثلاث طرق سريعة للتحقق من المواصفات اليوم.
محرر Swagger. الصق ملف YAML الخاص بك في محرر Swagger ويتحقق منه أثناء الكتابة، مع وضع خط تحت الأخطاء بأرقام الأسطر في الهامش الأيمن. إنها أسرع طريقة للتحقق السريع من ملف واحد، وهي مجانية. الحد الأقصى هو أنها مربع نص واحد: يتحقق من المستند ولكنه لا يفعل شيئًا بشأن ما إذا كانت واجهة برمجة التطبيقات الحقيقية الخاصة بك لا تزال تتطابق معه، وأنت تكتب YAML يدويًا بدون منشئ مخطط مرئي. لتعلم التنسيق، هذا جيد. بالنسبة للمواصفات التي يعتمد عليها فريق، إنها علامة تبويب واحدة في سير عمل يحتاج إلى العديد.
مدقق (Linter) مثل Spectral. Spectral من Stoplight هو واجهة سطر أوامر (CLI) مفتوحة المصدر تتجاوز الصلاحية الخام إلى قواعد الأسلوب. يتحقق من الصلاحية الهيكلية ويسمح لك بفرض مجموعة قواعد: كل عملية تحتاج إلى وصف، كل خاصية مخطط تحتاج إلى نوع، التسمية تتبع اتفاقيتك. Spectral هو حقًا أفضل أداة في فئته لحوكمة نمط المواصفات عبر العديد من الملفات، وإذا كان تصميم واجهة برمجة تطبيقات متسق هو اهتمامك، فإنه يستحق التبني. يمكنك تشغيله هكذا:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
المقايضة هي النطاق. Spectral يتحقق ويدقق المستند. إنه ليس مشغل طلبات؛ لن يخبرك ما إذا كانت واجهة برمجة التطبيقات التي تصفها المواصفات تتصرف بالفعل بالطريقة التي تدعيها المواصفات. هذا مستوى مختلف، وهو المستوى الذي تحدث فيه معظم مفاجآت الإنتاج.
نقطة نهاية مدقق عبر الإنترنت. ينشر مشروع Swagger خدمة مدقق تُرجع شارة "اجتياز" أو "فشل" لعنوان URL لمواصفات مستضافة. إنها مفيدة لشارة README، ولكنها أقل فائدة لحلقة إصلاح تفاعلية. لتغطية أعمق للخيارات المستقلة، نحتفظ بمجموعة من أفضل أدوات مدقق OpenAPI ودليل تفصيلي حول كيفية التحقق من مواصفات OpenAPI.
تتحقق هذه الثلاثة جميعها من المستند. لا يغلق أي منها الفجوة بين مواصفات صالحة وواجهة برمجة تطبيقات صحيحة. تلك الفجوة هي حيث يوجد القسم التالي.
أين يتناسب Apidog: التحقق من المواصفات، ثم إثبات تطابق واجهة برمجة التطبيقات معها
Apidog هي منصة متكاملة لواجهة برمجة التطبيقات: تقوم بتصميم المخطط، وتصحيح الأخطاء في الطلبات، وبناء سيناريوهات اختبار آلية، ونقاط نهاية وهمية، ونشر المستندات في مساحة عمل واحدة. التحقق من المواصفات ليس أداة منفصلة تقوم بإضافتها؛ إنه خاصية للعمل داخل المنصة.
عند استيراد ملف Swagger أو OpenAPI، أو تصميمه في المحرر المرئي، يقوم Apidog بتحليله والتحقق منه فورًا. مستند مشوه، $ref معطل، معلمة بدون نوع، كل هذه تظهر أثناء عملك، وليس بعد ثلاث أدوات لاحقًا. ولأن المحرر مرئي، فإن فئة كاملة من أخطاء YAML المكتوبة يدويًا لا تحدث أبدًا: لا يمكنك نسيان قيمة in لمعلمة عندما يكون الحقل عبارة عن قائمة منسدلة مطلوبة. المواصفات تكون صالحة بطبيعة بنائها.
هذا يتعامل مع المستند. المشكلة الأصعب هي الانجراف، وهو الاختلاف البطيء بين مواصفات تقول شيئًا وواجهة برمجة تطبيقات تفعل شيئًا آخر. لا يمكن لمدقق مستقل اكتشاف هذا، لأن الملف صالح؛ بل الخدمة قيد التشغيل هي الخطأ. هذا هو نمط الفشل وراء العديد من مستندات Swagger ومجموعات Postman المتغيرة.
يغلق Apidog هذه الفجوة بجعل المواصفات هي مصدر الحقيقة للاختبار. يمكنك إنشاء سيناريوهات اختبار مباشرة من مواصفات OpenAPI الخاصة بك، ثم التأكيد على أن الاستجابات الحقيقية تتطابق مع المخطط الذي أعلنته. عندما تقول المواصفات إن age هو عدد صحيح وتعيد واجهة برمجة التطبيقات سلسلة نصية، يفشل الاختبار، ويفشل مقابل المواصفات، وليس مقابل نسخة محفوظة يدويًا منها. يصبح سؤال المدقق مستمرًا: ليس "هل كان هذا الملف صالحًا عندما حفظته" بل "هل واجهة برمجة التطبيقات المباشرة لا تزال وفية لعقدها الآن". إذا كنت تريد آليات التأكيد، فإن تأكيدات API: دليل عملي يغطي التحقق من شكل الاستجابة والحالة والحقول.
بالنسبة للفرق التي ترغب في فرض التحقق تلقائيًا بدلاً من تذكره، يغطي Apidog أيضًا الحفاظ على توافق واجهات برمجة التطبيقات مع معايير OpenAPI كجزء من دورة التصميم.
تشغيل التحقق الموجه بالمواصفات في CI باستخدام Apidog CLI
المدقق الذي يعمل فقط عندما يفتح شخص ما المحرر هو مدقق سيتم تخطيه في النهاية. الحل هو وضع التحقق في مسار العمل (pipeline)، حيث يعمل مع كل عملية دفع (push) دون تدخل بشري. هذا هو الغرض من مشغل سطر الأوامر Apidog.
CLI هي حزمة npm تسمى apidog-cli. تقوم بتشغيل سيناريوهات الاختبار التي أنشأتها في Apidog، بدون واجهة رسومية، من أي بيئة تحتوي على Node.js. قم بتثبيتها بأمر واحد:
npm install -g apidog-cli
ثم قم بتشغيل سيناريو محفوظ، نفس السيناريو الذي يؤكد أن استجاباتك المباشرة تتطابق مع المواصفات، مقابل بيئة:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
بعض الملاحظات حول ما تفعله هذه الأعلام (flags). -t هو معرف سيناريو الاختبار. -e هو معرف البيئة، لذا يمكنك توجيه نفس عمليات التحقق إلى بيئة التحضير (staging) في طلب سحب (pull request) وإلى بيئة الإنتاج بعد النشر. -r يختار تنسيقات التقارير: cli لإخراج سجل البناء القابل للقراءة، ويمكنك إضافة html، json، أو junit لتغذية لوحة تحكم CI. يجب أن يكون --access-token في سر CI، وليس أبدًا مضمنًا. يمكنك إنشاء كل من الرمز المميز والأمر الجاهز من علامة التبويب CI/CD للسيناريو داخل Apidog. للحصول على تفاصيل الأعلام الكاملة، قم بتشغيل apidog run --help أو اقرأ دليل Apidog CLI الكامل.
التفصيل الذي يجعل هذا بوابة حقيقية: يخرج CLI برمز حالة غير صفري عندما يفشل التأكيد. تقرأ أنظمة CI رمز الخروج هذا. يؤدي فحص المخطط الفاشل إلى فشل الخطوة، مما يفشل المهمة، مما يحظر الدمج. لذا في اللحظة التي تتوقف فيها واجهة برمجة التطبيقات الخاصة بك عن مطابقة عقد OpenAPI الخاص بها، يتحول البناء إلى اللون الأحمر، قبل نشر التغيير، وليس بعد أن يفتح المستهلك تذكرة. هذا هو الفرق بين التحقق من ملف مرة واحدة والتحقق من العقد في كل تثبيت. نفس سلوك رمز الخروج هو سبب ملاءمة المشغل لأي منصة CI، تمامًا مثل تشغيل مجموعات Postman في CI بدون Newman.
قم بتنزيل Apidog إذا كنت تريد التحقق من المواصفات واختبار العقد في نفس المكان الذي يصمم فيه فريقك واجهة برمجة التطبيقات بالفعل.
سير عمل تحقق عملي
بجمع القطع معًا، إليك تسلسل يكتشف أخطاء المواصفات في كل مرحلة بدلاً من المرحلة الأخيرة فقط:
- التصميم أو الاستيراد في محرر متحقق. سواء قمت باستيراد ملف Swagger موجود أو بنيته في مصمم Apidog المرئي، يتم تحليل المستند والتحقق منه هيكليًا عند الإدخال. تظهر المراجع المعطلة والأنواع المفقودة على الفور.
- التدقيق اللغوي للأسلوب إذا كان لديك مجموعة قواعد. إذا كانت مؤسستك تفرض قواعد التسمية والوصف، فقم بتشغيل Spectral كفحص سريع قبل الالتزام (pre-commit). الصلاحية وأسلوب المؤسسة اهتمامات مختلفة؛ غطِّ كليهما.
- إنشاء الاختبارات من المواصفات. حوّل مستند OpenAPI إلى سيناريوهات اختبار بحيث تكون تأكيداتك مرتبطة بنفس التعريف الذي تنشره، وليس نسخة منفصلة تتغير.
- حماية كل عملية دفع باستخدام CLI. اربط
apidog runبمسار عملك بحيث يؤدي عدم تطابق المواصفات مع الواقع إلى فشل البناء تلقائيًا. - تعامل مع المواصفات كمصدر للحقيقة. عندما يتغير التصميم، تشير الاختبارات إلى نفس الملف، لذلك لا يوجد شيء يدوي للحفاظ على المزامنة.
الخطوتان 1 و 2 تتحققان من المستند. الخطوات من 3 إلى 5 تتحقق من العقد. أنت بحاجة إلى كليهما، وأرخص مكان للقيام بكل ذلك هو مساحة عمل واحدة بدلاً من أربعة علامات تبويب للمتصفح.
النسخة المختصرة
يلتقط مدقق Swagger الأخطاء الهيكلية، والمراجع المعطلة، والأنواع المفقودة، وملفات YAML المشوهة، التي تكون غير مرئية عند كتابتها ومكلفة عندما يقرأها شخص آخر. التحقق من المستند هو الحد الأدنى، وليس الأقصى. الأخطاء التي تصل بالفعل إلى الإنتاج هي تلك التي تتوقف فيها مواصفات صالحة بهدوء عن مطابقة واجهة برمجة تطبيقات متغيرة، ولا يمكن لأي مدقق على مستوى الملف رؤية تلك الأخطاء.
الحل هو التحقق في طبقتين ووضع كليهما في مكان واحد: التحقق من المستند أثناء تصميمه، ثم التحقق من العقد في كل عملية دفع عن طريق تأكيد الاستجابات الحقيقية مقابل المواصفات. يقوم Apidog بالأول عن طريق البناء والثاني من خلال سيناريوهات يقوم مشغل apidog-cli بحمايتها في CI. تبقى المواصفات هي مصدر الحقيقة، ويتحول البناء إلى اللون الأحمر في اللحظة التي ينجرف فيها الواقع عنها، ويتوقف ملف Swagger المعطل عن كونه شيئًا تكتشفه بعد فوات الأوان.