पाइपलाइन अवलोकन
पाइपलाइन प्रतिदिन सुबह 6 बजे UTC पर GitHub Actions (validate-and-release.yml) के माध्यम से चलती है और main में हर उस पुश पर चलती है जो scripts/, config/, या pyproject.toml को प्रभावित करता है। इसे मैन्युअल रूप से भी ट्रिगर किया जा सकता है, जिसमें रिलीज़ को बाध्य करने या लाइव API परीक्षणों को छोड़ने के विकल्प होते हैं।
पाइपलाइन चरण
Section titled “पाइपलाइन चरण” Download Validate Spectral Lint ┌──────┐ ┌──────────┐ ┌─────────────┐ │ Fetch │───────▶│Schemathesis│────▶│ Discover │ │ specs │ │Constraints│ │ violations │ └──────┘ └──────────┘ └─────────────┘ │ Spectral Gate Reconcile ┌─────────────┐ ┌──────────┐ │ Enforce │◀───│Apply fixes│ │ thresholds │ │to specs │ └─────────────┘ └──────────┘ │ Release ┌──────────┐ │ Package │ │ & tag │ └──────────┘1. डाउनलोड
Section titled “1. डाउनलोड”scripts/download.py आधिकारिक F5 XC OpenAPI स्पेक ZIP को docs.cloud.f5.com से प्राप्त करता है। यह सशर्त GET अनुरोधों के लिए HTTP ETag हेडर का उपयोग करता है — यदि अपस्ट्रीम बंडल में कोई बदलाव नहीं हुआ है, तो डाउनलोड छोड़ दिया जाता है। निकाली गई JSON स्पेक्स specs/original/ में सहेजी जाती हैं।
2. मान्यकरण
Section titled “2. मान्यकरण”scripts/validate.py लाइव F5 XC API के विरुद्ध दो प्रकार के परीक्षण संचालित करता है:
- Schemathesis — प्रॉपर्टी-आधारित परीक्षण जो स्पेक के अनुसार यादृच्छिक वैध/अवैध पेलोड उत्पन्न करता है और जांचता है कि API स्पेक की बाधाओं से सहमत है या नहीं।
- बाधा मान्यकरण — सभी 10 OpenAPI बाधा श्रेणियों (स्ट्रिंग लंबाई, पैटर्न, संख्यात्मक सीमाएं, आवश्यक फ़ील्ड, enums, ऐरे सीमाएं, ऑब्जेक्ट संरचना, संरचना, निर्भरताएं, डेटा प्रकार) के लिए लक्षित परीक्षण।
विसंगतियां reports/validation_report.json में लिखी जाती हैं।
3. Spectral लिंट (खोज)
Section titled “3. Spectral लिंट (खोज)”scripts/spectral_lint.py --mode discover मूल स्पेक्स के विरुद्ध spectral-pipeline.yaml का उपयोग करके Spectral CLI चलाता है। यह OAS3 गुणवत्ता समस्याओं को खोजता है — गायब servers ब्लॉक, गायब संपर्क जानकारी, बिना टैग के ऑपरेशन, अप्रयुक्त कंपोनेंट स्कीमा, डुप्लिकेट operationIds, अमान्य उदाहरण, और विवरणों में स्क्रिप्ट टैग।
उल्लंघनों को Discrepancy ऑब्जेक्ट में परिवर्तित किया जाता है और reports/spectral_report.json में लिखा जाता है। पूर्ण नियम सेट के लिए Spectral नियम देखें।
4. समन्वय
Section titled “4. समन्वय”scripts/reconcile.py दोनों रिपोर्ट फ़ाइलों का उपभोग करता है और प्रत्येक स्पेक पर सुधार लागू करता है:
- बाधा सुधार अवलोकित API व्यवहार के आधार पर स्कीमा बाधाओं को समायोजित करते हैं (शिथिल, कड़ा, जोड़ना, हटाना)। लागू किए गए सुधार देखें।
- Spectral सुधार स्पेक्स को servers, संपर्क जानकारी, टैग, सुरक्षा मेटाडेटा से समृद्ध करते हैं, और निष्क्रिय कंपोनेंट्स को हटाते हैं।
- सुरक्षा मेटाडेटा हमेशा इंजेक्ट किया जाता है यदि
security_schemeकॉन्फ़िग मौजूद है, भले ही Spectral ने इसे फ़्लैग न किया हो।
सुधारी गई स्पेक्स release/specs/ में लिखी जाती हैं और सहेजने से पहले openapi-spec-validator से मान्य की जाती हैं। यदि कोई सुधारी गई स्पेक मान्यकरण में विफल होती है, तो मूल को फ़ॉलबैक के रूप में उपयोग किया जाता है।
5. Spectral गेट
Section titled “5. Spectral गेट”scripts/spectral_lint.py --mode gate release/specs/ में समन्वित स्पेक्स के विरुद्ध Spectral को पुनः चलाता है। गेट त्रुटि और चेतावनी गणनाओं की कॉन्फ़िगर करने योग्य सीमाओं (validation.yaml में spectral.gate.max_errors और spectral.gate.max_warnings) के विरुद्ध जांच करता है।
6. रिलीज़
Section titled “6. रिलीज़”scripts/release.py समन्वित स्पेक्स को एक संस्करणित ZIP आर्काइव में पैकेज करता है। संस्करण अपस्ट्रीम स्पेक मेटाडेटा तिथि से प्राप्त YYYY.MM.DD-<patch> प्रारूप का उपयोग करते हैं। रिलीज़ में शामिल हैं:
- व्यक्तिगत डोमेन स्पेक फ़ाइलें (268 JSON फ़ाइलें)
- सभी डोमेन को संयोजित करने वाला एक मर्ज किया गया
openapi.json - लागू किए गए प्रत्येक सुधार को सूचीबद्ध करने वाला एक
CHANGELOG.md - एक
VALIDATION_REPORT.mdसारांश
CI जॉब ZIP संलग्न करके एक GitHub Release बनाता है, जिसे v<version> टैग किया जाता है। जब कुछ भी नहीं बदला है तो एक कंटेंट हैश डुप्लिकेट रिलीज़ को रोकता है।
दस्तावेज़ीकरण अपडेट
Section titled “दस्तावेज़ीकरण अपडेट”एक समानांतर CI जॉब scripts/generate_docs.py का उपयोग करके मान्यकरण रिपोर्ट से docs/01-validation-report.mdx उत्पन्न करता है, फिर यदि सामग्री बदली है तो एक PR खोलता है।