ภาพรวมของ Pipeline

Pipeline ทำงานทุกวันเวลา 6:00 UTC ผ่าน GitHub Actions (validate-and-release.yml) และทุกครั้งที่มีการ push ไปยัง main ที่เปลี่ยนแปลง scripts/, config/, หรือ pyproject.toml นอกจากนี้ยังสามารถทริกเกอร์ด้วยตนเองพร้อมตัวเลือกในการบังคับเผยแพร่หรือข้ามการทดสอบ API แบบ live ได้

ขั้นตอนของ Pipeline

 Download         Validate          Spectral Lint
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ Fetch │───────▶│Schemathesis│────▶│  Discover   │
 │ specs │        │Constraints│     │  violations │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral Gate       Reconcile
                ┌─────────────┐    ┌──────────┐
                │  Enforce    │◀───│Apply fixes│
                │  thresholds │    │to specs   │
                └─────────────┘    └──────────┘
                       │
                    Release
                 ┌──────────┐
                 │  Package  │
                 │  & tag    │
                 └──────────┘

1. ดาวน์โหลด

scripts/download.py ดึงไฟล์ ZIP ของ F5 XC OpenAPI spec อย่างเป็นทางการจาก docs.cloud.f5.com โดยใช้ HTTP ETag headers สำหรับ conditional GET requests — หากไฟล์ bundle ต้นทางไม่มีการเปลี่ยนแปลง จะข้ามการดาวน์โหลด ไฟล์ JSON specs ที่แตกไฟล์แล้วจะอยู่ใน specs/original/

2. ตรวจสอบความถูกต้อง

scripts/validate.py จัดการการทดสอบ 2 ประเภทกับ F5 XC API แบบ live:

• Schemathesis — การทดสอบแบบ property-based ที่สร้าง payload แบบสุ่มทั้งที่ถูกต้องและไม่ถูกต้องตาม spec แล้วตรวจสอบว่า API สอดคล้องกับ constraints ของ spec หรือไม่
• Constraint validation — การทดสอบแบบเจาะจงสำหรับ OpenAPI constraint ทั้ง 10 หมวดหมู่ (ความยาว string, pattern, ขอบเขตตัวเลข, required fields, enums, ขอบเขต array, โครงสร้าง object, composition, dependencies, ชนิดข้อมูล)

ความไม่สอดคล้องจะถูกเขียนลงใน reports/validation_report.json

3. Spectral Lint (ค้นพบ)

scripts/spectral_lint.py --mode discover รัน Spectral CLI กับ specs ต้นฉบับโดยใช้ spectral-pipeline.yaml ซึ่งจะค้นหาปัญหาคุณภาพ OAS3 — บล็อก servers ที่หายไป, ข้อมูลติดต่อที่หายไป, operations ที่ไม่มี tag, component schemas ที่ไม่ได้ใช้งาน, operationIds ที่ซ้ำกัน, examples ที่ไม่ถูกต้อง, และ script tags ใน descriptions

การละเมิดจะถูกแปลงเป็นออบเจ็กต์ Discrepancy และเขียนลงใน reports/spectral_report.json ดู กฎ Spectral สำหรับชุดกฎทั้งหมด

4. ปรับแก้ไข

scripts/reconcile.py ใช้ข้อมูลจากไฟล์รายงานทั้งสองและปรับแก้ไขทุก spec:

• การแก้ไข Constraint ปรับ schema constraints (ผ่อนคลาย, เข้มงวดขึ้น, เพิ่ม, ลบ) ตามพฤติกรรม API ที่สังเกตได้ ดู การแก้ไขที่ใช้
• การแก้ไข Spectral เพิ่มเติม specs ด้วย servers, ข้อมูลติดต่อ, tags, security metadata และลบ components ที่ไม่ได้ใช้งาน
• Security metadata จะถูกเพิ่มเสมอหากมีการกำหนดค่า security_scheme อยู่ แม้ว่า Spectral จะไม่ได้ตั้งค่าสถานะก็ตาม

specs ที่แก้ไขแล้วจะถูกเขียนลงใน release/specs/ และตรวจสอบด้วย openapi-spec-validator ก่อนบันทึก หาก spec ที่แก้ไขแล้วไม่ผ่านการตรวจสอบ จะใช้ spec ต้นฉบับเป็นตัวสำรอง

5. Spectral Gate

scripts/spectral_lint.py --mode gate รัน Spectral อีกครั้งกับ specs ที่ปรับแก้ไขแล้วใน release/specs/ gate จะตรวจสอบจำนวน error และ warning เทียบกับเกณฑ์ที่กำหนดค่าได้ (spectral.gate.max_errors และ spectral.gate.max_warnings ใน validation.yaml)

หมายเหตุ

เฟส 1 (ปัจจุบัน): เกณฑ์เป็น null (เตือนเท่านั้น) ตั้ง max_errors: 0 เพื่อบังคับใช้ gate แบบ zero-error

6. เผยแพร่

scripts/release.py จัดแพ็กเกจ specs ที่ปรับแก้ไขแล้วเป็นไฟล์ ZIP archive ที่มีเวอร์ชัน เวอร์ชันใช้รูปแบบ YYYY.MM.DD-<patch> ที่ได้มาจากวันที่ metadata ของ spec ต้นทาง การเผยแพร่ประกอบด้วย:

• ไฟล์ spec แต่ละโดเมน (268 ไฟล์ JSON)
• ไฟล์ openapi.json ที่รวมทุกโดเมนเข้าด้วยกัน
• CHANGELOG.md ที่แสดงรายการการแก้ไขทุกรายการที่ใช้
• สรุป VALIDATION_REPORT.md

งาน CI จะสร้าง GitHub Release พร้อมไฟล์ ZIP ที่แนบมา แท็กด้วย v<version> content hash จะป้องกันการเผยแพร่ซ้ำเมื่อไม่มีอะไรเปลี่ยนแปลง

การอัปเดตเอกสาร

งาน CI แบบคู่ขนานจะสร้าง docs/01-validation-report.mdx จากรายงานการตรวจสอบโดยใช้ scripts/generate_docs.py จากนั้นเปิด PR หากเนื้อหามีการเปลี่ยนแปลง