الإصلاحات المطبقة على المواصفات الأصلية

يطبق المُسوّي (scripts/reconcile.py) أربع فئات من الإصلاحات على المواصفات الأصلية. إصلاحات القيود تغيّر عقود واجهة برمجة التطبيقات لتتوافق مع السلوك الملاحظ. أما جميع الإصلاحات الأخرى فهي تعديلات على البيانات الوصفية فقط ولا تغيّر عقود واجهة برمجة التطبيقات.

إصلاحات القيود

تعمل هذه الإصلاحات على ضبط قيود مخطط OpenAPI بحيث تتطابق المواصفة مع ما تفرضه واجهة برمجة التطبيقات الحية فعلياً. يتم تنفيذ كل إصلاح بواسطة كائن Discrepancy يُنتَج أثناء مرحلة التحقق.

الاستراتيجية	المُحفِّز	ما تفعله	تغيير العقد
تخفيف	SPEC_STRICTER	المواصفة ترفض قيماً تقبلها واجهة برمجة التطبيقات. تخفض minLength/minimum، وترفع maxLength/maximum، وتضيف قيم enum مفقودة.	نعم — توسيع القيم المقبولة
تشديد	SPEC_LOOSER	المواصفة تقبل قيماً ترفضها واجهة برمجة التطبيقات. ترفع minLength/minimum، وتخفض maxLength/maximum، وتقيّد قيم enum بالقيم الملاحظة.	نعم — تضييق القيم المقبولة
إضافة	MISSING_CONSTRAINT	واجهة برمجة التطبيقات تفرض قيداً غير موثّق في المواصفة. تضيف القيد إلى المخطط.	نعم — إضافة قيد جديد
إزالة	EXTRA_CONSTRAINT	المواصفة تعلن عن قيد تتجاهله واجهة برمجة التطبيقات. تزيل القيد من المخطط.	نعم — إزالة القيد

تنبيه

إصلاحات القيود تغيّر عقد واجهة برمجة التطبيقات. ولا تُطبَّق إلا عندما تكون مدعومة بأدلة من Schemathesis أو اختبارات التحقق من القيود ضد واجهة برمجة التطبيقات الحية.

أنواع القيود المدعومة

فئات قيود OpenAPI العشر التي يتم اختبارها وإصلاحها:

• طول النص — minLength، maxLength
• النمط — pattern (تعبير نمطي)
• الحدود الرقمية — minimum، maximum، exclusiveMinimum، exclusiveMaximum
• الحقول المطلوبة — required
• قيم التعداد — enum
• حدود المصفوفات — minItems، maxItems، uniqueItems
• بنية الكائن — additionalProperties، properties، propertyNames
• التركيب — oneOf، anyOf، allOf
• التبعيات — dependentRequired، dependentSchemas
• أنواع البيانات — type، format

إثراءات Spectral

تعالج هذه الإصلاحات مشكلات جودة OAS3 التي اكتشفها فحص Spectral. وهي تضيف أو تصحح البيانات الوصفية دون تغيير سلوك واجهة برمجة التطبيقات.

حقن كتلة الخوادم

القاعدة: oas3-api-servers | تغيير العقد: لا

تضيف قالب عنوان URL لمستأجر F5 XC إلى المواصفات التي تفتقر إلى كتلة servers:

"servers": [{
  "url": "https://{tenant}.console.ves.volterra.io",
  "description": "F5 Distributed Cloud API",
  "variables": {
    "tenant": {
      "default": "example-tenant",
      "description": "Your F5 XC tenant name"
    }
  }
}]

يأتي عنوان URL للخادم وقيم المتغيرات من spectral.servers في validation.yaml.

حقن معلومات الاتصال

القاعدة: info-contact | تغيير العقد: لا

تضيف معلومات الاتصال إلى info.contact للمواصفات التي تفتقر إليها:

"contact": {
  "name": "F5 Distributed Cloud",
  "url": "https://docs.cloud.f5.com",
  "email": "support@f5.com"
}

تأتي القيم من spectral.contact في validation.yaml.

اشتقاق وسوم العمليات

القاعدة: operation-tags | تغيير العقد: لا

يشتق وسماً من بادئة مسار URL للعمليات غير الموسومة. بالنسبة لمسار مثل /api/config/namespaces/{namespace}/healthchecks، يكون الوسم config (الجزء الثاني غير المعامل من المسار). يُضاف الوسم إلى كل من مصفوفة tags الخاصة بالعملية وقائمة tags على مستوى المواصفة.

إزالة المكونات غير المستخدمة

القاعدة: oas3-unused-component | تغيير العقد: لا

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

إزالة تكرار معرّفات العمليات

القاعدة: operation-operationId-unique | تغيير العقد: لا

تلحق طريقة HTTP كلاحقة (مثل ListItems_get) عندما تتشارك عمليات متعددة نفس operationId. هذا يجعل كل معرّف عملية فريداً لمولّدات الشفرة البرمجية.

إزالة الأمثلة/القيم الافتراضية غير الصالحة

القاعدة: oas3-valid-schema-example | تغيير العقد: لا

تزيل قيم example أو default من المخططات عندما لا تتوافق القيمة مع قيود المخطط نفسه (نوع خاطئ، خارج النطاق، إلخ). تمنع مولّدات الشفرة البرمجية من إنتاج حمولات نموذجية غير صالحة.

تجريد وسوم السكربت

القاعدة: no-script-tags-in-markdown | تغيير العقد: لا

تجرّد وسوم <script> من حقول description باستخدام استبدال بالتعبيرات النمطية. بعض المواصفات الأصلية تحتوي على وسوم سكربت محقونة تعطّل عارضات التوثيق.

البيانات الوصفية للأمان

تغيير العقد: لا (توثيق فقط)

تتلقى كل مواصفة نظام أمان apiKeyAuth إذا لم يكن موجوداً بالفعل. يُحقن هذا دائماً بغض النظر عمّا إذا كان Spectral قد أشار إليه.

"components": {
  "securitySchemes": {
    "apiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "F5 XC API Token (format: APIToken <token>)"
    }
  }
},
"security": [{ "apiKeyAuth": [] }]

يأتي تعريف النظام من spectral.security_scheme في validation.yaml. هذا يخبر مستهلكي واجهة برمجة التطبيقات بكيفية المصادقة لكنه لا يغيّر السلوك أثناء التشغيل.

تنسيق JSON

تغيير العقد: لا

تمر جميع مواصفات JSON المُخرَجة عبر مُضغط مصفوفات متوافق مع Biome (_compact_short_arrays في scripts/utils/spec_loader.py). يتم طي المصفوفات القصيرة التي تتسع ضمن 120 حرفاً في سطر واحد:

// Before
"enum": [
  "ACTIVE",
  "INACTIVE"
]

// After
"enum": ["ACTIVE", "INACTIVE"]

المصفوفات التي تتجاوز حد طول السطر تبقى متعددة الأسطر.

أولوية الإصلاح

عندما يمكن تطبيق استراتيجيات إصلاح متعددة، يستخدم المُسوّي ترتيب أولوية مُهيأ في reconciliation.priority:

1. existing — استخدام قيد المواصفة الحالي إذا كان صالحاً
2. discovery — استخدام السلوك المكتشف لواجهة برمجة التطبيقات الحية
3. inferred — الاستنتاج من الأنماط عبر نقاط النهاية المشابهة

يتم التحقق من كل مواصفة مُصلَحة باستخدام openapi-spec-validator بعد تطبيق جميع الإصلاحات. إذا فشل التحقق، تُستخدم المواصفة الأصلية كبديل ويُسجَّل الإصلاح كخطأ.