قواعد التحقق في Spectral

يستخدم المشروع Spectral للتحقق من OAS3 ببنية ذات تكوينين تفصل أدوات CI/الأدوات الخارجية عن المنطق المخصص لخط الأنابيب.

بنية التكوينين

`.spectral.yaml` — التكوين الأساسي

يُستخدم بواسطة GitHub Super-Linter وأي أداة CI خارجية. يمتد من spectral:oas (مجموعة قواعد OAS المدمجة). لا يحتوي على دوال مخصصة — وهذا يبقيه متوافقاً مع الأدوات التي تشغل Spectral دون الوصول إلى مجلد spectral/functions/.

extends:
  - "spectral:oas"

rules:
  path-params: "off"
  operation-tags: warn
  oas3-api-servers: warn
  info-contact: warn
  oas3-unused-component: warn
  operation-operationId-unique: error
  oas3-valid-schema-example: error
  no-script-tags-in-markdown: warn
  operation-description: info
  info-description: info

`spectral-pipeline.yaml` — تكوين خط الأنابيب

يُستخدم بواسطة scripts/spectral_lint.py (في وضعي الاكتشاف والبوابة). يمتد من التكوين الأساسي ويضيف دالة f5-path-params المخصصة:

extends:
  - "./.spectral.yaml"

functionsDir: "./spectral/functions"
functions:
  - f5-path-params

rules:
  f5-path-params:
    description: "Path parameters must be declared and used"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: f5-path-params

لماذا تم تعطيل `path-params`

قاعدة path-params المدمجة في Spectral تُبلّغ خطأً عن واجهات F5 XC APIs التي تستخدم أسماء معاملات منقطة مثل {metadata.namespace} و{metadata.name}. القاعدة المدمجة لا تحلل النقاط في أسماء المعاملات، لذا تُبلّغ عنها كمعاملات غير مُعلنة.

دالة f5-path-params المخصصة (spectral/functions/f5-path-params.js) تتعامل بشكل صحيح مع الأسماء المنقطة عن طريق مطابقة محتوى {placeholder} الكامل مع أسماء المعاملات المُعلنة. تتحقق من المعاملات على مستوى المسار ومستوى العملية، وتُبلّغ عن الأخطاء في كلا الاتجاهين:

عنصر نائب في مسار URL لا يوجد له تعريف معامل مطابق
معامل مسار مُعلن لا يظهر في مسار URL

مرجع القواعد

القواعد القابلة للإصلاح التلقائي

يتم إصلاح هذه القواعد تلقائياً بواسطة المُوفّق عند اكتشاف انتهاكات. راجع الإصلاحات المُطبّقة لمزيد من التفاصيل حول كل إصلاح.

القاعدة	الخطورة	طريقة الإصلاح	الوصف
`oas3-api-servers`	تحذير	`_add_servers`	يجب أن تحتوي المواصفة على كتلة `servers`
`info-contact`	تحذير	`_add_contact`	يجب أن يتضمن `info` حقل `contact`
`operation-tags`	تحذير	`_add_tags`	يجب أن تحتوي كل عملية على وسم واحد على الأقل
`oas3-unused-component`	تحذير	`_remove_unused_component`	لا مخططات مكونات غير مُشار إليها
`operation-operationId-unique`	خطأ	`_deduplicate_operation_id`	يجب أن تكون جميع معرفات العمليات فريدة
`oas3-valid-schema-example`	خطأ	`_fix_schema_example`	يجب أن تتطابق الأمثلة/القيم الافتراضية مع مخططاتها
`no-script-tags-in-markdown`	تحذير	`_strip_script_tags`	لا وسوم `<script>` في الأوصاف
`f5-path-params`	خطأ	—	يجب تعريف معاملات المسار واستخدامها

القواعد غير القابلة للإصلاح

تم تخفيض خطورة هذه القواعد إلى info لأنه لا يمكن إصلاحها تلقائياً بشكل ذي معنى:

القاعدة	الخطورة	الوصف
`operation-description`	معلومات	يجب أن تحتوي العمليات على وصف
`info-description`	معلومات	يجب أن تحتوي معلومات API على وصف

التكامل مع خط الأنابيب

محول Spectral (scripts/spectral_lint.py) يعمل في وضعين:

وضع الاكتشاف (قبل المُوفّق)

make spectral-lint
# Equivalent to: python -m scripts.spectral_lint --mode discover

يفحص specs/original/ ويكتب reports/spectral_report.json. يستهلك المُوفّق هذا التقرير إلى جانب تقرير التحقق.

وضع البوابة (بعد المُوفّق)

make spectral-gate
# Equivalent to: python -m scripts.spectral_lint --mode gate

يفحص release/specs/ ويكتب reports/spectral_gate_report.json. يُرجع رمز خروج 1 إذا تجاوزت الانتهاكات الحدود المُكوّنة.

تعيين الانتهاكات

يتم تحويل انتهاكات Spectral إلى كائنات Discrepancy بثلاثة أنواع فرعية:

فئة قاعدة Spectral	DiscrepancyType	أمثلة على القواعد
عنصر مطلوب مفقود	`SPECTRAL_MISSING`	`oas3-api-servers`, `info-contact`, `operation-tags`
عنصر موجود غير صالح	`SPECTRAL_INVALID`	`oas3-valid-schema-example`, `no-script-tags-in-markdown`
كود ميت	`SPECTRAL_UNUSED`	`oas3-unused-component`