التحقق من معايير OpenAPI استشر أخطاء في ملف Swagger قبل أن تُعطل العملاء

مُعَيَّن OpenAPI هو عقد بين واجهة برمجة تطبيقاتك وكل ما يستهلكها — مثل العناصر المُولَّدة تلقائيًا، وخدمات المُحاكاة، ووثائق التوثيق، وبرامج الاختبار. المشكلة هي أن مقاربات التطبيق لا تُنتج استثناءات عند وجود خطأ في المعايير. بل تُنتج إجابات خاطئة بشكل سكين، والشيء الوحيد الذي تسمعه هو عندما تُنتج مكتبات العملاء كودًا غير قابل للإستخدام أو تُظهر الوثائق بدون نقاط نهاية.

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

لماذا يهم تنسيق معاييرك أكثر من مجرد الوثائق

يُعتقد أن معظم المطورين أن معايير OpenAPI هي وثيقة توثيق — شيء يُستخدم لتشغيل واجهة برمجة تطبيقات مثل Swagger UI أو Redoc. هذا يُعد نصف الصورة. إن المعايير هي أيضًا مصدر الحقيقة بالنسبة للإدراة التالية:

• إعادة التوليد — أدوات مثل openapi-generator و swagger-codegen تُولّد مُحاكاة الخوادم وملفات المكتبات من المعايير. أي معايير مُحرفة تُنتج كودًا مُحرفًا.
• اختبار العقد — أدوات مثل Dredd و Schemathesis تختبر واجهة برمجة تطبيقاتك حسب المعايير. أي معايير غير صحيحة تؤدي إلى فشل في تشغيل الاختبارات أو إنتاج نتائج خاطئة.
• أجهزة المُحاكاة — أدوات مثل Prism و أدوات مشابهة تُقدّم إجابات مُحاكاة بناءً على القيم المُقدّمة في المعايير. أي معايير خاطئة تُنتج مُحاكاة خاطئة.
• تكوين البوابة — يمكن لـ AWS API Gateway و Kong وغيرها استيراد معايير OpenAPI لضبط التوجيه، والتحقق من الهوية، والتحقق من المدخلات. أي معايير غير صحيحة تُفقد أو تُضبط بشكل خاطئ.

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

OpenAPI 2.0 مقابل 3.0 مقابل 3.1: الفروق في الإصدارات التي تُسبب مشاكل

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

• OpenAPI 2.0 (Swagger) — يستخدم swagger: "2.0". تُوضع الطلبات في parameters المسائل الشائعة التي يجب مراقبتها in: body. تُوجد التعاريف في definitionsالقيم المنطقية تبقى كنصوص. components/schemas. لا تدعم oneOf, anyOf، أو not في مستوى المعايير.
• OpenAPI 3.0.x — يستخدم openapi: "3.0.x". تنتقل الطلبات إلى requestBody. تُدمج المعايير تحت components. تدعم oneOf, anyOf, allOfو، و not. تضيف links و callbacks.
• OpenAPI 3.1.0 — تُطابق تمامًا معايير JSON Schema 2020-12. nullable تُستبدل بـ type: [string, null]. exclusiveMinimum/exclusiveMaximum تغيير من الأرقام إلى الأعداد. $schema مسموح بها في المعايير.

الخطأ الأكثر شيوعًا في التحويل: نسخ معايير 2.0 وتعديل حقل الإصدار إلى 3.0.0 بدون نقل الطلبات من parameters ل requestBody. تبدو المعايير صحيحة كـ JSON أو YAML ولكنها تفشل في التحقق من المعنى.

أخطاء شائعة في المعايير وأين تختبئ

تُصنف أخطاء المعايير في أنماط متوقعة. فيما يلي الأنواع الأكثر شيوعًا في الكودات الحقيقية:

مجالات مفقودة

يجب أن يكون لكل عملية على الأقل إجابة من نوع 2xx مُعرفة. يجب أن يكون كل مُعلّم له name وقيمة in . يجب أن يكون المُعلّم المُعلن في الرابط (مثلاً /users/{id}) له مُعلّم مُعرف مع in: path و required: true. أي غياب من هذه العناصر يُنتج معايير قابلة للتحليل تقنيًا ولكنها تُسبب فشلًا في المُحققين والمحوّلين للنماذج.

مسارات $ref غير صحيحة

أ $ref التي تشير إلى مكون غير موجود هي أبرز أخطاء في المعايير. تبدو المُرجعية صحيحة — $ref: "#/components/schemas/UserProfile" — لكن المكون المُراد تغييره تم تغييره أو حذفه. تقبل مُحلّل JSON أو YAML هذا دون ملاحظة. فقط مُحقق معايير يُكتشف هذا.

مراجع خارجية $ref مُحفوفة بمخاطر أكبر — فهي تشير إلى ملفات أو روابط خارجية قد لا تكون متاحة في كل البيئات. اجعل هذه المراجع داخلية قبل توزيع المعايير أو استخدامها مع أدوات لا تحلّل المراجع الخارجية.

أنواع المعايير الخاطئة

تُظهر أخطاء في أنواع المعايير بشكل خفيف. إعلان type: integer على حقل يُرجع قيمًا من نوع float. استخدام format: date-time مع حقل يُرجع أوقات Unix (أعداد صحيحة). تعريف enum مع قيم لا تتوافق مع المُعلن type. تمر المعايير بتحليل YAML ولكن تُنتج خصائص خاطئة في المُحولين للعملاء.

المرجع المُتسلسل

مُعايير تُشير إليها — بشكل مباشر أو من خلال سلسلة من $ref القيم — تُسبب توقفًا لا نهائيًا أو توقفًا في أدوات إعادة التوليد وبرامج الوثائق. تُكتشف معظم المُحققين هذه المرجع المُتسلسلة، لكنها قد تكون صعبة التخلص منها في معايير متداخلة. الحل هو عادةً تقليل الدورة باستخدام معايير مخصصة للحالة المتكررة.

أخطاء هيكلية مقابل أخطاء معنوية

لا تُعتبر أخطاء التحقق متماثلة. فهم الفرق يساعدك على ترتيب الحلول:

• أخطاء هيكلية — لا تتوافق المعايير مع معايير OpenAPI. تُغيب الحقول المطلوبة، أو تُستخدم أسماء خاطئة، أو أنواع لا تتوافق مع صيغة المعايير. تُكتشف هذه الأخطاء من خلال التحقق الصارم للمعايير ويُمنع معظم الأدوات من العمل.
• أخطاء معنوية — المعايير هي صحيحة من حيث الهيكل وتمر التحقق من المعايير، لكنها تصف شيئًا لا يمكن أن يعمل. مثال: نقطة نهاية تحتوي على معلّم في الرابط لكن لا يوجد تعريف للمعلّم. مثال: معايير الإجابة تستخدم allOf مع مُعلّمات متناقضة. تُكتشف هذه الأخطاء من خلال معايير التحقق المعمّقة، وليس من التحقق الأساسي للمواصفات.

تُكتشف معظم أدوات التحقق عبر الإنترنت والبرامج المُدمجة في السطر الأوّل أخطاء هيكلية. لاستكشاف أخطاء معنوية، تحتاج إلى مُدقق مبني على قواعد مثل Spectral، والذي يُقيّم منطق المعايير وتوافقها.

مكونات/السُّمَات: تعريفات مُتكررة مقابل السُّمَات المُضمنة

أُدخلت OpenAPI 3.0 ميزة components/schemas كأفضل مكان لتعريف السُّمَات المُتكررة. التنازل:

• السُّمَات المُتكررة في المكونات — صحيحة عندما تظهر نفس السُّمَة في أماكن متعددة (مثلاً كائن User مُعادل من قبل عدة نقاط نهاية). استخدام $ref: "#/components/schemas/User" يُحافظ على المعايير مُختصرة ويُولّد فئة مُسمّاة واحدة في مكتبات العملاء.
• السُّمَات المُضمنة — صحيحة لأشكال الإجابة المُحددة لنقطة نهاية واحدة ولا تُستخدم مجددًا. تجنب التعبئة تُقلل من تلوث components/schemas بتعريفات مُستخدمة مرة واحدة تجعل المعايير صعبة القراءة.

النمط الخاطئ هو تعريف سُمَة في components/schemas وإلا تُستخدم. يمكن لمُدقّق مثل Spectral أن يُظهر السُّمَات غير المستخدمة، والتي غالبًا ما تشير إلى $ref التي كانت مُفترضة أن تشير إليها لكنها تشير إلى مكان آخر.

الطلبات المُدخلة مقابل المُعلّمات: أين تقع الأخطاء

في OpenAPI 3.0، تم تفكيك الطلبات المُدخلة والمتغيرات بشكل صارم:

• المُعلّمات — للقيم في المسارات، والمتغيرات، والرؤوس، والكُوكيز. كل مُعلّم هو قيمة بسيطة، وليس كائنًا معقدًا.
• الطلب المُدخل — للحملة (الجسم JSON، البيانات المُدخلة، أو تحميل الملفات). مطلوب للعمليات POST/PUT/PATCH التي تقبل جسمًا.

الخطأ الذي يُسببه المطورون عند التحول من 2.0: في Swagger 2.0، كانت الطلبات المُدخلة مُعلّمات مع in: body. في OpenAPI 3.0 هذا غير صحيح — in: body لا توجد. معايير تحتوي على in: body تُمرر التحقق من التحليل ولكنها تفشل في التحقق من المعايير، وتعمل أدوات إعادة التوليد إما على توقف أو تُستبعد الطلبات المُدخلة تلقائيًا.

كيفية التحقق من المعايير محليًا

أداة سطر الأوامر الثلاثة الموثوقة للتحقق المحلي، من الأبسط إلى الأكثر تفصيلاً:

swagger-cli

تحقق هيكلية سريع و $ref حل. مناسب لفحص سرعة:

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

تُظهر أخطاء الهيكل ومسارات مُضطربة. $ref لا تُكتشف مشاكل معنوية أو مشاكل في التصميم.

Redocly CLI

تحقق هيكلية مع مجموعة قواعد قابلة للتعديل. مناسب لمستوى صارم في المعايير الإنتاجية:

npm install -g @redocly/cli
redocly lint openapi.yaml

تُكتشف غياب الوصفات، مراجع مُضطربة، وعديد من المشاكل المعنوية بشكل تلقائي.

Spectral

أداة مُحدّثة بشكل كبير. تُشغل مجموعة قواعد OpenAPI المُدمجة بالإضافة إلى القواعد المُحددة من قبلك. مناسب للفرق التي ترغب في تطبيق معايير تطبيقاتها:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

يُميّز Spectral بين الأخطاء (تُوقف المعايير) والتحذيرات (مُشكلات في التصميم أو التكامل)، لذا يمكنك إصلاح المشكلات المُحذرة أولاً دون تأثير من القواعد التوصية.

التحقق في المتصفح دون تثبيت أي شيء

إذا كنت ترغب في التحقق من المعايير بسرعة — دون تثبيت أداة سطر الأوامر أو تشغيل بناء — فإن مُحقق معايير OpenAPI / Swagger على iotools.cloud يُشغل بالكامل في المتصفح. أدخل معاييرك بصيغة YAML أو JSON وستُظهر أخطاء هيكلية، مسارات مُضطربة، مجالات مفقودة، وأخطاء متعلقة بالإصدارات المختلفة بين OpenAPI 2.0، 3.0، و3.1. $ref مفيد لفحص سريع قبل التسليم، لفحص معايير أرسلها شخص آخر، أو لفحص معايير أُولِّدت من التصاميم وتحتاج إلى تحقق قبل تشغيل إعادة التوليد.

بناء التحقق في سير عملك

التحقق الفوري يُعالج مشاكل فورية لكنه لا يمنع التراجعات. نهج أكثر استدامة:

مُدخل قبل التسليم

• — تشغيل قبل كل تسليم. لا تصل معايير مُتضررة إلى المخزن. swagger-cli validate أو spectral lint خطوة في سلسلة التصنيع (CI)
• — أضف التحقق من المعايير كخطوة مبكرة في سلسلة التصنيع، قبل أي خطوات إعادة التوليد أو التسليم التي تعتمد على المعايير. التحقق من المعايير المُولّدة
• — إذا أُولِّدت معاييرك من تسميات الكود (مثلاً springdoc، swagger-annotations، FastAPI)، فتحقق من المخرجات المولّدة، وليس فقط من التسميات. يمكن أن تُنتج خطأ في المخرجات أثناء تعارض التسميات أو عدم كفايتها. الهدف هو جعل المعايير غير الصالحة مستحيلة للإطلاق — وليس مجرد شيء تُعالج عند تقرير مشكلة من قبل المستهلك.

التحقق من معايير OpenAPI: اكتشاف الأخطاء في ملفك Swagger قبل أن تُضر العملاء 2

قد يعجبك أيضاً