نظرة سريعة#
الإرشادات مجموعة قواعد Spectral باسم @api360/spectral-ruleset. تمتد من قواعد spectral:oas القياسية وتضيف القواعد المسمّاة في الصفحات الأخرى من هذا القسم.
| الملف الشخصي | لمن | الفروق |
|---|---|---|
vendor (المزوّد) | واجهة منتج ينشرها مزوّد | الإصدار الرئيسي في المسار؛ وتوثّق طلبات POST المنشئة Idempotency-Key؛ ويُفحص متغيّر المسار كتلميح |
platform | تعريفات النطاقات الثلاثة عشر في المنصة | بلا جزء إصدار؛ وبلا قواعد التكرار الآمن؛ ولا يُفحص متغيّر المسار |
ينتهي التشغيل بالرمز 0 حين تكون كل ملاحظة دون شدة الإفشال (warn افتراضياً) أو مشمولة بقائمة الاستثناءات، وبالرمز 1 فيما عدا ذلك.
شغّلها#
npm install @api360/spectral-ruleset npx api360-spectral --profile vendor openapi/product.yaml npx api360-spectral --profile platform --exclude index.json --report-dir spectral-report openapi/domains
يطبع الأمر الملاحظات لكل تعريف ولكل قاعدة، ويكتب summary.md وsummary.json وfindings.json في مجلد التقرير. الخيار --fail-severity error يمرّر التحذيرات؛ والخيار --no-allowlist يُظهر كل شيء.
تأتي الحزمة من سجل حزم GitLab لمجموعة api360-ai. وجّه النطاق @api360 إليه في .npmrc:
@api360:registry=https://gitlab.com/api/v4/projects/84641482/packages/npm/في خط البناء#
المستودع الذي فيه ملفات OpenAPI يضمّن المهمة المشتركة، وهي تحمل مجموعة القواعد بداخلها ولا تحتاج سجلاً:
include: - project: 'api360-ai/pipeline-orchestrator' ref: main file: 'ci-templates/spectral-lint.gitlab-ci.yml' variables: SPECTRAL_PROFILE: vendor SPECTRAL_PATHS: openapi
تعمل المهمة في خطوط طلبات الدمج، وتفشل عند ملاحظة لا تشملها قائمة الاستثناءات، وتحفظ التقرير كملف ناتج.
قائمة الاستثناءات#
الملاحظة التي لا يستطيع التعريف إصلاحها بعد تدخل قائمة استثناءات مؤرَّخة، لا تجاهلاً شاملاً. يسمّي كل بند القاعدة والسبب والتغيير الذي يغلقه وتاريخ المراجعة وعدداً لكل تعريف. ملاحظة واحدة فوق العدد تُفشل التشغيل، وبند تجاوز تاريخ مراجعته يُفشله أيضاً، فيعني «نظيف» أن كل ملاحظة متبقية مكتوبة ولها مسؤول.
تتحقق منه#
| عائلة القواعد | القواعد |
|---|---|
| التسمية | api360-property-snake-case وapi360-query-param-snake-case وapi360-path-param-snake-case وapi360-enum-value-case وapi360-path-kebab-case |
| الأخطاء | api360-error-envelope-schema وapi360-error-responses-declared |
| الترقيم | api360-pagination-params وapi360-pagination-response |
| التكرار الآمن | api360-idempotency-key-header وapi360-idempotency-responses |
| الإصدارات | api360-version-info وapi360-version-in-path وapi360-platform-unversioned-paths |
| الإيقاف | api360-deprecation-headers |
| الأمان | api360-operation-security وapi360-no-apikey-in-query |
انظر أيضاً#
- إرشادات تصميم الواجهات البرمجية: القواعد كنص.
- للمزوّدين: نشر المنتج.