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

คู่มือนี้อธิบายเวิร์กโฟลว์การพัฒนาสำหรับ F5 XC API Enrichment Pipeline

เริ่มต้นอย่างรวดเร็ว

การตั้งค่าครั้งแรก

# 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            │
└─────────────────────┘     └─────────────────────────────┘

ขั้นตอน Pipeline

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

โครงสร้างไดเรกทอรี

ไดเรกทอรี	วัตถุประสงค์	สถานะ Git
specs/original/	F5 source specs	Gitignored
specs/discovered/	API discovery output	Tracked (openapi.json, session.json)
docs/specifications/api/	Generated domain specs	Gitignored
scripts/	Python pipeline scripts	Tracked
config/	Pipeline configuration	Tracked
reports/	Generated reports	Gitignored

รูปแบบเวิร์กโฟลว์

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 จากการตอบสนองจริง
• ค่าเริ่มต้น
• การตรวจสอบ Pattern
• ตัวอย่างการตอบสนอง

2. เวิร์กโฟลว์การเผยแพร่

การเผยแพร่เป็นแบบอัตโนมัติ:

1. กำหนดการรายวัน (6 AM UTC) หรือการ push ไปยัง main จะเรียกใช้เวิร์กโฟลว์
2. การตรวจสอบ ETag จะพิจารณาว่า F5 specs เปลี่ยนแปลงหรือไม่
3. Pipeline ประมวลผลและเพิ่มประสิทธิภาพ specs
4. เวอร์ชันคำนวณจาก git tags: git describe --tags --abbrev=0
5. สร้าง Direct commit + tag (ไม่มี version bump PR)
6. สร้าง GitHub Release พร้อม changelog
7. เผยแพร่เอกสารไปยัง GitHub Pages

กฎการเพิ่มเวอร์ชัน:

เงื่อนไข	ประเภทการเพิ่ม	ตัวอย่าง
[major] ใน commit	Major	1.0.0 → 2.0.0
BREAKING CHANGE ใน commit	Major	1.0.0 → 2.0.0
เพิ่ม domain spec ใหม่	Minor	1.0.0 → 1.1.0
การเปลี่ยนแปลงอื่นๆ	Patch	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 จริง: ค่าจริงที่พบในการใช้งานจริง
• พฤติกรรมเริ่มต้น: ค่าที่เซิร์ฟเวอร์กำหนดเมื่อไม่มีการระบุฟิลด์
• รูปแบบการตอบสนอง: รูปร่างข้อมูลจริง

การกำหนดค่าการค้นพบ

config/discovery.yaml

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

  schema_inference:
    sample_size: 3
    detect_patterns: true
    detect_constraints: true

ส่วนขยายการค้นพบ

การค้นพบเพิ่ม extension x-discovered-* ลงใน specs:

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

รายงานการวิเคราะห์ข้อจำกัด

reports/constraint-analysis.md

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

config/enrichment.yaml

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

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

กฎ Spectral Linting

config/spectral.yaml

extends:
  - spectral:oas

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

ส่วนขยาย OpenAPI

Enrichment pipeline ใช้ vendor extensions เพื่อฝังข้อมูล metadata การตรวจสอบและค่าเริ่มต้น

ประเภทส่วนขยาย

ส่วนขยาย	ความหมาย	ผลกระทบ
x-f5xc-server-default	F5 XC API server ใช้ค่านี้เมื่อไม่มีการระบุฟิลด์	ฟิลด์เป็นแบบไม่จำเป็น การละเว้นฟิลด์จะสร้างพฤติกรรมเริ่มต้นตามที่ระบุ
x-f5xc-recommended-value	F5 XC web console กรอกค่านี้ล่วงหน้าสำหรับทรัพยากรใหม่	ฟิลด์ไม่มีค่าเริ่มต้นจากเซิร์ฟเวอร์ แต่ค่านี้แสดงถึงการกำหนดค่าทั่วไป
x-f5xc-recommended-oneof-variant	F5 XC คอนโซลเลือก OneOf variant นี้ล่วงหน้า	ระบุตัวเลือกทั่วไปเมื่อมีหลายตัวเลือกที่ไม่สามารถใช้ร่วมกันได้
x-f5xc-conflicts-with	แสดงรายการคุณสมบัติอื่นที่ไม่สามารถใช้ร่วมกับฟิลด์นี้ได้	คุณสมบัตินี้เป็นส่วนหนึ่งของกลุ่ม OneOf โดยระบุได้เพียงหนึ่งในคุณสมบัติที่ขัดแย้งกัน

ส่วนขยายฟิลด์ที่จำเป็น

ส่วนขยาย	แหล่งที่มา	วัตถุประสงค์
x-ves-required: "true"	F5 XC original spec	ฟิลด์ต้องการค่าที่ไม่เป็นศูนย์/ไม่ว่างเปล่า
x-f5xc-required-for	Enrichment pipeline	สถานะที่จำเป็นตามบริบทเฉพาะ

บริบทของ 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 variant ที่แนะนำ
x-f5xc-conflicts-with	การยกเว้นร่วมกันกับคุณสมบัติ OneOf อื่น

x-f5xc-server-default

ประเภท: boolean

เมื่อเป็น true แสดงว่าค่า default ที่ระบุนั้นถูกบังคับใช้โดย F5 XC API server ฟิลด์ที่มีส่วนขยายนี้สามารถละเว้นจากคำขอ API ได้อย่างปลอดภัย โดยเซิร์ฟเวอร์จะใช้ค่าเริ่มต้นโดยอัตโนมัติ

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

x-f5xc-recommended-value

ประเภท: any (ตรงกับประเภทฟิลด์)

ระบุค่าที่ F5 XC web console ใช้เป็นค่าเริ่มต้นที่กรอกล่วงหน้า ค่านี้ไม่ได้บังคับใช้โดยเซิร์ฟเวอร์ แต่แสดงถึงการกำหนดค่าเริ่มต้นทั่วไปสำหรับทรัพยากรใหม่ที่สร้างผ่านคอนโซล

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

x-f5xc-recommended-oneof-variant

ประเภท: object (แผนที่ชื่อกลุ่มไปยังชื่อ variant)

สำหรับ schema ที่มีกลุ่มฟิลด์ที่ไม่สามารถใช้ร่วมกันได้ จะระบุว่า variant ใดเป็นตัวเลือกเริ่มต้นหรือพบบ่อยที่สุด โดย key คือชื่อกลุ่ม OneOf และ value คือชื่อฟิลด์ variant ที่แนะนำ

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

x-f5xc-conflicts-with

ประเภท: array ของ strings

เพิ่มใน: v3.2.0 (Issue #494)

ประกาศความสัมพันธ์การยกเว้นร่วมกันระหว่างสมาชิกกลุ่ม OneOf ได้มาโดยอัตโนมัติจาก extension x-ves-oneof-field-* ช่วยให้เครื่องมือปลายทาง (Terraform, CLI, MCP) สามารถตรวจสอบข้อขัดแย้งที่ระดับ schema แทนที่จะเป็น runtime

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 providers สามารถสร้างกฎการตรวจสอบ
• เครื่องมือ CLI สามารถแจ้งเตือนเกี่ยวกับการรวมฟิลด์ที่ขัดแย้ง
• ผู้ช่วย AI สามารถสร้างการกำหนดค่า OneOf ที่ถูกต้อง
• ส่วนขยาย IDE สามารถให้การเติมโค้ดอัตโนมัติที่คำนึงถึงข้อขัดแย้ง

แหล่งที่มา: ได้มาโดยอัตโนมัติจาก F5 native extension x-ves-oneof-field-* ระหว่าง pipeline enrichment

ผลกระทบของกฎการตรวจสอบ

Enricher ตรวจสอบ 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 array ต้องมีอย่างน้อย N รายการ
ves.io.schema.rules.string.min_bytes: N	ถ้า N >= 1 string ต้องมีอย่างน้อย N bytes

ทรัพยากรที่มีค่าเริ่มต้นจากเซิร์ฟเวอร์

ทรัพยากรบางอย่างรับ spec ว่างเปล่าได้เนื่องจากเซิร์ฟเวอร์ใช้ค่าเริ่มต้น:

ทรัพยากร	ค่าเริ่มต้นที่ใช้โดยเซิร์ฟเวอร์
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

รูปแบบค่าเริ่มต้น

รูปแบบ	ประเภท	ตัวอย่าง
\{\}	Object ว่างเปล่า (การเลือกตัวเลือก)	monitoring: \{\}
[]	Array ว่างเปล่า	expected_status_codes: []
0	ตัวเลข	jitter: 0
""	String	expected_response: ""
false	Boolean	use_http2: false

การเพิ่มค่าเริ่มต้นที่ค้นพบ

1. สร้างทรัพยากรใน F5 XC ด้วย spec ขั้นต่ำผ่าน API
2. อ่านทรัพยากรกลับมาเพื่อดูค่าที่เซิร์ฟเวอร์กำหนด
3. บันทึกค่าเริ่มต้นใน config/discovered_defaults.yaml
4. รัน pipeline: make pipeline
5. ตรวจสอบด้วย: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

การแก้ไขปัญหา

Pre-commit ใช้เวลานานเกินไป

Pipeline รันทุก commit เพื่อให้แน่ใจว่ามีความสม่ำเสมอ สำหรับ commit งานที่กำลังดำเนินการ:

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

ข้อผิดพลาด Lint บน Generated Specs

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

แก้ไขปัญหาใน enrichment/normalization config ไม่ใช่ไฟล์ output

ระบบเวอร์ชัน

เวอร์ชันได้มาจาก git tags (เช่น v2.0.38) ซึ่งขจัดปัญหา race conditions ที่ทำให้เกิด merge conflicts บน PR พร้อมกัน

# 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"

Specs หายไปหลัง Clone

Generated specs ถูก gitignore:

make build  # Downloads and generates everything

ไฟล์ขนาดใหญ่ถูกบล็อก

เพิ่มการยกเว้นใน .pre-commit-config.yaml:

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

อ้างอิงด่วน

Make Targets

Target	คำอธิบาย
make build	Build แบบเต็ม (download + pipeline)
make rebuild	Build ใหม่อย่างรวดเร็ว (ข้าม download)
make download	ดาวน์โหลด specs (ETag cached)
make download-force	บังคับดาวน์โหลด
make pipeline	รัน enrichment pipeline
make lint	Spectral linting
make serve	เซิร์ฟเวอร์เอกสารในเครื่อง
make discover	API discovery (ต้องใช้ VPN)
make push-discovery	Commit ข้อมูล discovery
make clean	ลบไฟล์ที่สร้างขึ้น
make pre-commit-run	รันการตรวจสอบคุณภาพทั้งหมด

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

ตัวแปร	วัตถุประสงค์
F5XC_API_URL	F5 XC tenant API URL
F5XC_API_TOKEN	โทเค็นการยืนยันตัวตน API

ไฟล์สำคัญ

ไฟล์	วัตถุประสงค์
.etag	ETag ที่ดาวน์โหลดล่าสุด
CHANGELOG.md	Changelog ที่สร้างอัตโนมัติ
config/enrichment.yaml	กฎ Enrichment
config/normalization.yaml	กฎ Normalization
config/discovery.yaml	การตั้งค่า Discovery
config/spectral.yaml	กฎ Linting
scripts/utils/version_calculator.py	การคำนวณเวอร์ชันจาก tag

หมายเหตุ: เวอร์ชันได้มาจาก git tags (เช่น v2.0.38) ไม่ใช่จากไฟล์ .version