คู่มือการพัฒนา

การตั้งค่า

# Clone and install dev dependencies
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Install Spectral CLI (required for linting stages)
npm install -g @stoplight/spectral-cli

make dev-install จะสร้าง virtualenv ในไดเรกทอรี .venv/ และติดตั้งโปรเจกต์พร้อมกับ dev extras (pytest, ruff, mypy)

ตัวแปรสภาพแวดล้อม

การตรวจสอบ API แบบสด (live) ต้องการ:

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

หากไม่มีตัวแปรเหล่านี้ make validate จะทำงานในโหมด dry-run แทน

การรัน Pipeline

Pipeline แบบเต็ม

make all
# Runs: download → validate → spectral-lint → reconcile → spectral-gate → release

ขั้นตอนแต่ละขั้น

make download        # Fetch upstream specs
make validate        # Run live API tests (requires API token)
make validate-dry    # Dry run (no API calls)
make spectral-lint   # Spectral discover mode on original specs
make reconcile       # Apply fixes from both reports
make spectral-gate   # Spectral quality gate on reconciled specs
make release         # Build release package

เอกสารประกอบ

make docs-generate   # Regenerate docs/01-validation-report.mdx from reports
make docs            # Build full documentation site
make docs-serve      # Local dev server with hot reload

การรันการทดสอบ

make test           # pytest with coverage
make lint           # ruff check + format check
make typecheck      # mypy type checking
make ci-test        # All three (used in CI)

Pre-commit hooks จะทำงานอัตโนมัติเมื่อ commit หากมีการติดตั้งไว้:

make pre-commit-install   # Install git hooks
make pre-commit           # Run all hooks manually

โครงสร้างโปรเจกต์

scripts/
  download.py           # Stage 1: Fetch specs from F5
  validate.py           # Stage 2: Live API testing
  spectral_lint.py      # Stage 3/5: Spectral linting adapter
  reconcile.py          # Stage 4: Apply fixes to specs
  release.py            # Stage 6: Package release
  generate_docs.py      # Generate MDX from reports
  utils/
    auth.py             # F5 XC API authentication
    constraint_validator.py  # Constraint testing + Discrepancy types
    report_generator.py      # Report formatting
    schemathesis_runner.py   # Schemathesis test orchestration
    spec_loader.py           # Spec I/O + JSON formatting

config/
  validation.yaml       # Pipeline configuration
  endpoints.yaml        # Baseline endpoints for live testing

spectral/
  functions/
    f5-path-params.js   # Custom Spectral function

docs/                   # Starlight MDX documentation
tests/                  # pytest test suite
release/specs/          # Output: reconciled spec files
reports/                # Output: validation and Spectral reports

การเพิ่ม Fix Method ใหม่

การเพิ่ม Spectral auto-fix ใหม่ให้กับ reconciler:

เพิ่มกฎ ใน .spectral.yaml โดยกำหนด severity ตามต้องการ
เปิดใช้งาน auto-fix ใน config/validation.yaml ภายใต้ spectral.auto_fix:
```
spectral:
  auto_fix:
    your-new-rule: true
```

เพิ่ม fixer method ใน SpecReconciler ในไฟล์ scripts/reconcile.py:

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # Modify spec in place
    # Return spec if changed, None if no change needed
    return spec

ลงทะเบียน ใน dispatcher _apply_spectral_fix:

spectral_fixers = {
    # ... existing fixers ...
    "spectral:your-new-rule": self._fix_your_rule,
}

เพิ่มการทดสอบ ที่ครอบคลุม fix method ใหม่

การเพิ่มกฎ Spectral ใหม่

การเพิ่มกฎ Spectral แบบกำหนดเองที่มีฟังก์ชัน JavaScript:

สร้างฟังก์ชันในไฟล์ spectral/functions/your-rule.js โดย export ฟังก์ชัน default ที่รับพารามิเตอร์ (targetVal, options, context) และคืนค่าเป็นอาร์เรย์ของอ็อบเจกต์ {message, path}

ลงทะเบียนในไฟล์ spectral-pipeline.yaml:

functions:
  - f5-path-params
  - your-rule

rules:
  your-rule:
    description: "What it checks"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: your-rule

CI Pipeline

GitHub Actions workflow (validate-and-release.yml) จะทำงานเมื่อ:

กำหนดเวลา: ทุกวันเวลา 6:00 UTC
Push ไปยัง main: เมื่อไฟล์ใน scripts/, config/, หรือ pyproject.toml มีการเปลี่ยนแปลง
เรียกใช้ด้วยตนเอง: พร้อมตัวเลือกสำหรับ forced release หรือ dry-run

Workflow มีทั้งหมดสี่ jobs:

validate — ดาวน์โหลด specs, รัน validation, Spectral lint, reconcile, Spectral gate
check-release-needed — เปรียบเทียบ content hashes เพื่อตัดสินใจว่าจำเป็นต้อง release หรือไม่
release — แพ็กเกจและสร้าง GitHub Release (เฉพาะเมื่อเนื้อหามีการเปลี่ยนแปลง)
update-docs — สร้าง 01-validation-report.mdx ใหม่และเปิด PR หากมีการเปลี่ยนแปลง

Job notify จะสร้าง GitHub issue หาก job ใดล้มเหลว

เวิร์กโฟลว์ Branch และ PR

การเปลี่ยนแปลงทั้งหมดจะดำเนินตาม: Issue -> Branch -> PR -> CI ผ่าน -> Merge

ชื่อ branch: feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
PR ต้องลิงก์กับ issue (Closes #N ในคำอธิบาย)
CI checks ที่จำเป็น: Check linked issues และ Lint Code Base
แนะนำให้ใช้ squash merge; branches จะถูกลบอัตโนมัติหลัง merge

ดู CONTRIBUTING.md สำหรับกฎเวิร์กโฟลว์ทั้งหมด