دليل التطوير

يصف هذا الدليل سير عمل التطوير لخط أنابيب إثراء API الخاص بـ F5 XC.

البداية السريعة

الإعداد لأول مرة

# Clone the repository
git clone https://github.com/f5-sales-demo/api-specs-enriched.git
cd api-specs-enriched

# Create virtual environment and install dependencies
make install

# Install pre-commit hooks
make pre-commit-install

# Download specs and run pipeline
make build

# Preview documentation locally
make serve

التطوير اليومي

# Quick rebuild (uses cached specs)
make rebuild

# Run all quality checks
make pre-commit-run

# Preview documentation
make serve

نظرة عامة على البنية

تصميم المجلدين

┌─────────────────────┐     ┌─────────────────────────────┐
│   specs/original/   │────▶│   docs/specifications/api/  │
│   (READ-ONLY)       │     │   (GENERATED)               │
│   - Downloaded      │     │   - Domain specs            │
│   - Gitignored      │     │   - Master spec             │
│   - ETag cached     │     │   - GitHub Pages            │
└─────────────────────┘     └─────────────────────────────┘

تدفق خط الأنابيب

Download (ETag) → Enrich → Normalize → Merge → Lint → Serve
     │              │          │         │       │
     ▼              ▼          ▼         ▼       ▼
 270 specs     Branding    Fix refs   23 domains  Spectral
             + Grammar    + Types    + Master     rules

هيكل الدليل

الدليل	الغرض	حالة Git
`specs/original/`	مواصفات F5 المصدر	مُستثنى من Git
`specs/discovered/`	مخرجات اكتشاف API	مُتتبَّع (openapi.json, session.json)
`docs/specifications/api/`	مواصفات النطاق المُولَّدة	مُستثنى من Git
`scripts/`	نصوص Python لخط الأنابيب	مُتتبَّع
`config/`	إعداد خط الأنابيب	مُتتبَّع
`reports/`	التقارير المُولَّدة	مُستثنى من Git

أنماط سير العمل

1. سير عمل الاكتشاف

المتطلبات المسبقة:

اتصال VPN ببيئة F5 XC
بيانات اعتماد API صالحة

# Set credentials
export F5XC_API_URL="https://your-tenant.console.ves.volterra.io/api"
export F5XC_API_TOKEN="your-api-token"

# Run discovery
make discover

# View results
jq '.statistics' specs/discovered/session.json

# Commit for CI/CD
make push-discovery

ما يلتقطه الاكتشاف:

الحقول المطلوبة/الاختيارية الفعلية
قيم Enum من الاستجابات المباشرة
القيم الافتراضية
عمليات التحقق من الأنماط
أمثلة الاستجابات

2. سير عمل الإصدار

الإصدارات مؤتمتة:

الجدول اليومي (6 صباحًا بتوقيت UTC) أو الدفع إلى الفرع الرئيسي يُشغّل سير العمل
يحدد فحص ETag ما إذا كانت مواصفات F5 قد تغيرت
يُعالج خط الأنابيب المواصفات ويُثريها
يُحسب الإصدار من وسوم git: git describe --tags --abbrev=0
يُنشأ commit مباشر + وسم (بدون PR لرفع الإصدار)
يُنشأ إصدار GitHub مع سجل التغييرات
يُنشر التوثيق على GitHub Pages

قواعد رفع الإصدار:

الشرط	نوع الرفع	مثال
`[major]` في الـ commit	رئيسي	1.0.0 → 2.0.0
`BREAKING CHANGE` في الـ commit	رئيسي	1.0.0 → 2.0.0
إضافة مواصفة نطاق جديدة	ثانوي	1.0.0 → 1.1.0
أي تغيير آخر	تصحيحي	1.0.0 → 1.0.1

3. سير عمل التطوير

# Create feature branch
git checkout -b feature/my-change

# Make changes to config or scripts

# Test locally
make pipeline
make lint

# Commit (pre-commit hooks run automatically)
git add .
git commit -m "feat: add new enrichment rule"

# Push and create PR
git push -u origin feature/my-change
gh pr create

التعمق في الاكتشاف

ما هو الاكتشاف؟

يستكشف الاكتشاف واجهة F5 XC API المباشرة للعثور على:

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

إعداد الاكتشاف

discovery:
  exploration:
    namespaces:
      - "system"
      - "shared"
    methods:
      - "GET"
      - "OPTIONS"
    max_endpoints_per_run: 500

  schema_inference:
    sample_size: 3
    detect_patterns: true
    detect_constraints: true

امتدادات الاكتشاف

يُضيف الاكتشاف امتدادات x-discovered-* إلى المواصفات:

{
  "properties": {
    "name": {
      "type": "string",
      "x-discovered-required": true,
      "x-discovered-pattern": "^[a-z][a-z0-9-]*$",
      "x-discovered-examples": ["my-app", "prod-lb"]
    }
  }
}

تقرير تحليل القيود

make constraint-report

عملية الإصدار

محتويات حزمة الإصدار

f5xc-api-specs-v1.0.14.zip
├── openapi.json       # Master combined spec
├── openapi.yaml       # YAML format
├── domains/           # Individual domain specs
│   ├── api_security.json
│   ├── load_balancer.json
│   └── ...
├── index.json         # Metadata
├── CHANGELOG.md       # Release notes
└── README.md          # Usage instructions

تشغيل سير العمل يدويًا

gh workflow run sync-and-enrich.yml
gh run watch

دليل الإعداد

إعداد الإثراء

enrichment:
  branding:
    replacements:
      "Volterra": "F5 Distributed Cloud"
      "VES": "F5 XC"

  acronyms:
    API: "Application Programming Interface"
    DNS: "Domain Name System"

  grammar:
    enabled: true
    language_tool: true

إعداد التطبيع

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

قواعد فحص Spectral

extends:
  - spectral:oas

rules:
  operation-operationId: error
  operation-tags: warn

امتدادات OpenAPI

يستخدم خط أنابيب الإثراء امتدادات البائع لتضمين بيانات التحقق وقيم الافتراضية.

فئات الامتدادات

الامتداد	المعنى	الانعكاس
`x-f5xc-server-default`	يُطبق خادم F5 XC API هذه القيمة عند حذف الحقل	الحقل اختياري؛ حذفه ينتج السلوك الافتراضي الموثق
`x-f5xc-recommended-value`	تملأ واجهة F5 XC الويب هذه القيمة مسبقًا للموارد الجديدة	لا يوجد افتراضي للخادم للحقل لكن هذه القيمة تمثل الإعداد النموذجي
`x-f5xc-recommended-oneof-variant`	تختار وحدة تحكم F5 XC هذا المتغير من OneOf مسبقًا	يُحدد الخيار النموذجي عند وجود خيارات متعددة متنافية
`x-f5xc-conflicts-with`	يسرد الخصائص الأخرى التي لا يمكن استخدامها مع هذا الحقل	الخاصية جزء من مجموعة OneOf؛ يمكن تحديد خاصية واحدة فقط من الخصائص المتعارضة

امتدادات الحقول المطلوبة

الامتداد	المصدر	الغرض
`x-ves-required: "true"`	مواصفة F5 XC الأصلية	يتطلب الحقل قيمة غير صفرية/غير فارغة
`x-f5xc-required-for`	خط أنابيب الإثراء	الحالة المطلوبة حسب السياق

سياقات x-f5xc-required-for:

create: مطلوب عند إنشاء المورد
update: مطلوب عند تحديث المورد
minimum_config: مطلوب للحد الأدنى من الإعداد القابل للتطبيق

امتدادات القيم الافتراضية وOneOf

الامتداد	الغرض
`x-f5xc-server-default: true`	يُعلّم الإعدادات الافتراضية التي يُطبقها الخادم
`x-f5xc-recommended-value`	قيمة مُملأة مسبقًا في وحدة تحكم F5 XC
`x-f5xc-recommended-oneof-variant`	متغير OneOf الموصى به
`x-f5xc-conflicts-with`	التنافي المتبادل مع خصائص OneOf الأخرى

x-f5xc-server-default

النوع: boolean

عندما تكون true، تشير إلى أن قيمة default المرافقة مُفرَّضة بواسطة خادم F5 XC API. يمكن حذف الحقول التي تحمل هذا الامتداد بأمان من طلبات API — يُطبّق الخادم الإعداد الافتراضي تلقائيًا.

use_http2:
  type: boolean
  default: false
  x-f5xc-server-default: true

x-f5xc-recommended-value

النوع: any (يطابق نوع الحقل)

يحدد قيمة تستخدمها واجهة F5 XC الويب كإعداد افتراضي مُملأ مسبقًا. هذه القيمة غير مُفرَّضة من قبل الخادم لكنها تمثل الإعداد الأولي النموذجي للموارد الجديدة التي تُنشأ عبر وحدة التحكم.

timeout:
  type: integer
  x-f5xc-recommended-value: 3

x-f5xc-recommended-oneof-variant

النوع: object (خريطة من اسم المجموعة إلى اسم المتغير)

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

healthcheckCreateSpecType:
  type: object
  x-f5xc-recommended-oneof-variant:
    health_check: "http_health_check"

x-f5xc-conflicts-with

النوع: array من السلاسل النصية

تمت الإضافة: v3.2.0 (Issue #494)

يُعلن عن علاقات التنافي المتبادل بين أعضاء مجموعة OneOf. مُشتق تلقائيًا من امتدادات x-ves-oneof-field-*. يُتيح هذا للأدوات الأدنى (Terraform، CLI، MCP) التحقق من التعارضات على مستوى المخطط بدلاً من وقت التشغيل.

host_header:
  type: string
  x-f5xc-conflicts-with: ["use_origin_server_name"]

use_origin_server_name:
  type: object
  x-f5xc-conflicts-with: ["host_header"]

حالات الاستخدام:

يمكن لموفري Terraform توليد قواعد التحقق
يمكن لأدوات CLI التحذير من مجموعات الحقول المتعارضة
يمكن لمساعدي الذكاء الاصطناعي توليد إعدادات OneOf صحيحة
يمكن لإضافات IDE توفير الإكمال التلقائي المدرك للتعارضات

المصدر: مُشتق تلقائيًا من امتدادات F5 الأصلية x-ves-oneof-field-* أثناء إثراء خط الأنابيب.

انعكاسات قواعد التحقق

يفحص المُثري x-ves-validation-rules لاستنتاج الحالة المطلوبة:

القاعدة	الانعكاس
`ves.io.schema.rules.message.required: "true"`	الحقل مطلوب
`ves.io.schema.rules.uint32.gte: N`	إذا كان N >= 1 وبدون افتراضي للخادم، الحقل مطلوب
`ves.io.schema.rules.repeated.min_items: N`	إذا كان N >= 1، يتطلب المصفوفة N عنصر على الأقل
`ves.io.schema.rules.string.min_bytes: N`	إذا كان N >= 1، تتطلب السلسلة N بايت على الأقل

الموارد ذات الإعدادات الافتراضية المُطبَّقة من الخادم

تقبل بعض الموارد مواصفات فارغة لأن الخادم يُطبق الإعدادات الافتراضية:

المورد	الإعدادات الافتراضية المُطبَّقة من الخادم
`app_firewall`	`monitoring: \{\}`, `default_detection_settings: \{\}`
`rate_limiter`	`limits: []`, `user_identification: []`
`api_definition`	`swagger_specs: []`, default `api_groups`
`healthcheck`	`jitter: 0`, `jitter_percent: 0`, nested http_health_check defaults

بالنسبة لهذه الموارد، قد تكون x-f5xc-required-for.create بقيمة false حتى عندما تكون x-ves-required بقيمة true.

أنماط القيم الافتراضية

النمط	النوع	مثال
`\{\}`	كائن فارغ (اختيار نوع)	`monitoring: \{\}`
`[]`	مصفوفة فارغة	`expected_status_codes: []`
`0`	رقمي	`jitter: 0`
`""`	نصي	`expected_response: ""`
`false`	منطقي	`use_http2: false`

إضافة الإعدادات الافتراضية المُكتشَفة

إنشاء المورد في F5 XC بمواصفة بحد أدنى عبر API
قراءة المورد مجددًا لرؤية القيم التي طبّقها الخادم
توثيق الإعدادات الافتراضية في config/discovered_defaults.yaml
تشغيل خط الأنابيب: make pipeline
التحقق باستخدام: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

استكشاف الأخطاء وإصلاحها

pre-commit يستغرق وقتًا طويلاً

يعمل خط الأنابيب على كل commit لضمان الاتساق. بالنسبة للـ commits قيد التقدم:

git commit --no-verify -m "WIP: work in progress"
# Run before final commit: make pre-commit-run

فشل الاكتشاف

# Check VPN
ping your-tenant.console.ves.volterra.io

# Check credentials
echo $F5XC_API_TOKEN | head -c 10

# Check API URL format
echo $F5XC_API_URL
# Format: https://tenant.console.ves.volterra.io/api

أخطاء الفحص في المواصفات المُولَّدة

# Check lint report
cat reports/lint-report.json | jq '.errors'

أصلح المشكلات في إعداد الإثراء/التطبيع، وليس في ملفات المخرجات.

نظام الإصدار

يُشتق الإصدار من وسوم git (مثل v2.0.38)، مما يُزيل حالات التعارض التي كانت تُسبب تعارضات الدمج في PRs المتزامنة.

# Version is calculated dynamically from git tags
from scripts.utils.version_calculator import get_version_from_tags
version = get_version_from_tags()  # Returns "2.0.38"

مواصفات مفقودة بعد الاستنساخ

المواصفات المُولَّدة مُستثناة من Git:

make build  # Downloads and generates everything

ملف كبير محجوب

أضف الاستثناء إلى .pre-commit-config.yaml:

- id: check-added-large-files
  exclude: ^path/to/large/file\.json$

المرجع السريع

أهداف Make

الهدف	الوصف
`make build`	بناء كامل (تنزيل + خط الأنابيب)
`make rebuild`	إعادة بناء سريعة (تخطي التنزيل)
`make download`	تنزيل المواصفات (مخزنة مؤقتًا بـ ETag)
`make download-force`	فرض التنزيل
`make pipeline`	تشغيل خط أنابيب الإثراء
`make lint`	فحص Spectral
`make serve`	خادم التوثيق المحلي
`make discover`	اكتشاف API (يتطلب VPN)
`make push-discovery`	تثبيت بيانات الاكتشاف
`make clean`	إزالة الملفات المُولَّدة
`make pre-commit-run`	تشغيل جميع فحوصات الجودة

متغيرات البيئة

المتغير	الغرض
`F5XC_API_URL`	عنوان URL لـ API خاصة بمستأجر F5 XC
`F5XC_API_TOKEN`	رمز مصادقة API

الملفات الرئيسية

الملف	الغرض
`.etag`	آخر ETag تم تنزيله
`CHANGELOG.md`	سجل التغييرات المُولَّد تلقائيًا
`config/enrichment.yaml`	قواعد الإثراء
`config/normalization.yaml`	قواعد التطبيع
`config/discovery.yaml`	إعدادات الاكتشاف
`config/spectral.yaml`	قواعد الفحص
`scripts/utils/version_calculator.py`	حساب الإصدار المستند إلى الوسوم

ملاحظة: يُشتق الإصدار من وسوم git (مثل v2.0.38)، وليس من ملف .version.