مرجع الإعدادات

يتم التحكم في جميع سلوكيات خط المعالجة من خلال ملفي YAML في config/.

`config/validation.yaml`

إعدادات واجهة برمجة التطبيقات

api:
  base_url: "https://example-tenant.console.ves.volterra.io"
  tenant: "example-tenant"
  namespace: "example-namespace"
  timeout: 30
  retries: 3
  retry_delay: 2

الحقل	الوصف
`base_url`	عنوان URL الأساسي لواجهة برمجة تطبيقات وحدة تحكم F5 XC. يمكن تجاوزه بمتغير البيئة `F5XC_API_URL`.
`tenant`	اسم المستأجر المستخدم في مسارات واجهة برمجة التطبيقات.
`namespace`	مساحة الأسماء الافتراضية لعمليات CRUD.
`timeout`	مهلة طلب HTTP بالثواني.
`retries`	عدد محاولات إعادة المحاولة عند الفشل.
`retry_delay`	الثواني بين محاولات إعادة المحاولة.

قيم base_url و tenant و namespace في validation.yaml هي عناصر نائبة عامة. يجب عليك تهيئة هذه القيم لبيئتك عبر متغيرات البيئة قبل تشغيل خط المعالجة:

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_TENANT="example-tenant"
export F5XC_NAMESPACE="example-namespace"
export F5XC_API_TOKEN="your-api-token"

تأخذ متغيرات البيئة الأولوية على القيم الافتراضية في ملف YAML أثناء التشغيل.

إعدادات التنزيل

download:
  url: "https://docs.cloud.f5.com/docs-v2/downloads/f5-distributed-cloud-open-api.zip"
  output_dir: "specs/original"
  etag_cache: ".etag_cache"

الحقل	الوصف
`url`	عنوان URL لحزمة مواصفات OpenAPI الرسمية من F5 XC (بصيغة ZIP).
`output_dir`	مكان تخزين المواصفات المستخرجة.
`etag_cache`	الملف الذي يخزن علامة ETag الخاصة ببروتوكول HTTP للتنزيلات المشروطة.

فئات التحقق

عشر فئات تتوافق مع أنواع قيود مخطط OpenAPI. يمكن تمكين/تعطيل كل منها بشكل مستقل.

validation_categories:
  string_length:
    enabled: true
    keywords: ["minLength", "maxLength"]
    description: "Validate string length boundaries"

الفئة	الكلمات المفتاحية
`string_length`	`minLength`، `maxLength`
`pattern`	`pattern`
`numeric_bounds`	`minimum`، `maximum`، `exclusiveMinimum`، `exclusiveMaximum`
`required_fields`	`required`
`enum_values`	`enum`
`array_bounds`	`minItems`، `maxItems`، `uniqueItems`
`object_structure`	`additionalProperties`، `properties`، `propertyNames`
`composition`	`oneOf`، `anyOf`، `allOf`
`dependencies`	`dependentRequired`، `dependentSchemas`
`data_types`	`type`، `format`

إعدادات Schemathesis

schemathesis:
  enabled: true
  max_examples: 100
  hypothesis_phases:
    - generate
    - target
  stateful_testing: true
  base_url_override: null
  auth_header: "Authorization"
  auth_prefix: "APIToken"

الحقل	الوصف
`enabled`	تبديل تشغيل/إيقاف اختبار Schemathesis.
`max_examples`	الحد الأقصى لعدد حالات الاختبار المولدة لكل عملية.
`hypothesis_phases`	مراحل Hypothesis المراد تشغيلها (`generate`، `target`).
`stateful_testing`	تمكين الاختبار ذي الحالة القائم على الروابط عبر العمليات.
`base_url_override`	تجاوز عنوان URL الأساسي لواجهة برمجة التطبيقات للاختبارات. القيمة `null` تستخدم `api.base_url`.
`auth_header`	اسم ترويسة HTTP للمصادقة.
`auth_prefix`	تنسيق بادئة الرمز المميز (تُرسل الطلبات بصيغة `APIToken <token>`).

إعدادات التسوية

reconciliation:
  priority:
    - existing
    - discovery
    - inferred
  fix_strategies:
    tighter_spec: "relax"
    looser_spec: "tighten"
    missing_constraint: "add"
    extra_constraint: "remove"

الحقل	الوصف
`priority`	ترتيب الأولوية عندما تتعارض مصادر البيانات المتعددة.
`fix_strategies`	يربط كل نوع من التناقضات بإجراء الإصلاح الخاص به. انظر الإصلاحات المُطبقة.

إعدادات Spectral

spectral:
  enabled: true
  ruleset: "spectral-pipeline.yaml"
  auto_fix:
    oas3-api-servers: true
    info-contact: true
    operation-tags: true
    oas3-unused-component: true
    operation-operationId-unique: true
    oas3-valid-schema-example: true
    no-script-tags-in-markdown: true
  gate:
    max_errors: null
    max_warnings: null
  contact:
    name: "F5 Distributed Cloud"
    url: "https://docs.cloud.f5.com"
    email: "support@f5.com"
  servers:
    - url: "https://{tenant}.console.ves.volterra.io"
      description: "F5 Distributed Cloud API"
      variables:
        tenant:
          default: "example-tenant"
          description: "Your F5 XC tenant name"
  security_scheme:
    type: "apiKey"
    in: "header"
    name: "Authorization"
    description: "F5 XC API Token (format: APIToken <token>)"

الحقل	الوصف
`enabled`	تبديل تشغيل/إيقاف فحص Spectral بالكامل.
`ruleset`	ملف إعدادات Spectral المراد استخدامه (يستخدم خط المعالجة `spectral-pipeline.yaml`).
`auto_fix`	خريطة من اسم القاعدة إلى قيمة منطقية. القيمة `true` تعني أن المُسوّي سيصلح الانتهاكات.
`gate.max_errors`	الحد الأقصى المسموح به للأخطاء في بوابة ما بعد التسوية. القيمة `null` تعطل الفحص.
`gate.max_warnings`	الحد الأقصى المسموح به للتحذيرات. القيمة `null` تعطل الفحص.
`contact`	معلومات الاتصال المُدرجة في `info.contact` بواسطة مُصلح `info-contact`.
`servers`	مصفوفة الخوادم المُدرجة بواسطة مُصلح `oas3-api-servers`.
`security_scheme`	تعريف مخطط الأمان المُدرج في كل مواصفة.

إعدادات التقارير

reports:
  output_dir: "reports"
  formats:
    - json
    - html
    - markdown
  include_examples: true
  max_examples_per_issue: 5

إعدادات الإصدار

release:
  output_dir: "release"
  include_changelog: true
  include_validation_report: true
  version_from: "git"

الحقل	الوصف
`output_dir`	دليل مخرجات الإصدار.
`include_changelog`	تضمين `CHANGELOG.md` في حزمة الإصدار.
`include_validation_report`	تضمين تقرير التحقق في حزمة الإصدار.
`version_from`	مصدر الإصدار. القيمة `git` تستخلص الإصدار من تاريخ بيانات المواصفات الوصفية + رقم التصحيح.

`config/endpoints.yaml`

يحدد نقاط النهاية الأساسية المستخدمة للتحقق المباشر من واجهة برمجة التطبيقات. يربط كل إدخال اسم مورد منطقي بملف المواصفات الخاص به ومجموعة واجهة برمجة التطبيقات ومسارات CRUD.

هيكل نقطة النهاية

endpoints:
  healthcheck:
    resource: healthchecks
    domain_file: docs-cloud-f5-com.0124.public.ves.io.schema.healthcheck.ves-swagger.json
    api_group: config
    crud_operations:
      create: POST /api/config/namespaces/{namespace}/healthchecks
      read: GET /api/config/namespaces/{namespace}/healthchecks/{name}
      list: GET /api/config/namespaces/{namespace}/healthchecks
      update: PUT /api/config/namespaces/{namespace}/healthchecks/{name}
      delete: DELETE /api/config/namespaces/{namespace}/healthchecks/{name}
    test_priority: high
    description: "Health check configurations for origin monitoring"

الحقل	الوصف
`resource`	اسم مورد واجهة برمجة التطبيقات (يُستخدم في مسارات URL).
`domain_file`	اسم ملف مواصفات OpenAPI في `specs/original/`.
`api_group`	بادئة مجموعة واجهة برمجة التطبيقات (`config`، `web`، إلخ).
`crud_operations`	طريقة HTTP والمسار لكل عملية CRUD.
`test_priority`	`high` أو `medium` أو `low` — يتحكم في ترتيب تنفيذ الاختبارات.
`description`	وصف مقروء للمورد.

نقاط النهاية الأساسية الحالية

10 نقاط نهاية عبر ثلاثة نطاقات:

نقطة النهاية	النطاق	الأولوية
`healthcheck`	افتراضي	عالية
`origin_pool`	افتراضي	عالية
`app_firewall`	افتراضي	عالية
`service_policy`	افتراضي	متوسطة
`api_definition`	أمان واجهة برمجة التطبيقات	عالية
`api_discovery`	أمان واجهة برمجة التطبيقات	متوسطة
`api_groups`	أمان واجهة برمجة التطبيقات	متوسطة
`code_base_integration`	أمان واجهة برمجة التطبيقات	منخفضة
`data_type`	خصوصية البيانات	متوسطة
`sensitive_data_policy`	خصوصية البيانات	متوسطة

إضافة نقاط نهاية جديدة

لإضافة نقطة نهاية جديدة للتحقق:

ابحث عن اسم ملف المواصفات في specs/original/ (الصيغة: docs-cloud-f5-com.NNNN.*.ves-swagger.json)
أضف إدخالاً تحت endpoints: باتباع الهيكل الموضح أعلاه
أضف ربط ملف النطاق تحت domain_files: مع رقم أولوية
أضف اسم نقطة النهاية إلى test_order: في الموضع المطلوب