अपस्ट्रीम स्पेक्स पर लागू किए गए सुधार

रिकंसाइलर (scripts/reconcile.py) अपस्ट्रीम स्पेक्स पर चार श्रेणियों के सुधार लागू करता है। कंस्ट्रेंट सुधार API अनुबंधों को देखे गए व्यवहार से मिलाने के लिए बदलते हैं। अन्य सभी सुधार केवल मेटाडेटा से संबंधित हैं और API अनुबंधों में कोई परिवर्तन नहीं करते।

कंस्ट्रेंट सुधार

ये सुधार OpenAPI स्कीमा कंस्ट्रेंट्स को समायोजित करते हैं ताकि स्पेक लाइव API द्वारा वास्तव में लागू किए जाने वाले नियमों से मेल खाए। प्रत्येक सुधार सत्यापन के दौरान उत्पन्न Discrepancy ऑब्जेक्ट द्वारा संचालित होता है।

रणनीति	ट्रिगर	यह क्या करता है	अनुबंध परिवर्तन
रिलैक्स	SPEC_STRICTER	स्पेक उन मानों को अस्वीकार करता है जो API स्वीकार करता है। minLength/minimum कम करता है, maxLength/maximum बढ़ाता है, अनुपस्थित enum मान जोड़ता है।	हाँ — स्वीकृत मानों का दायरा बढ़ाता है
टाइटन	SPEC_LOOSER	स्पेक उन मानों को स्वीकार करता है जो API अस्वीकार करता है। minLength/minimum बढ़ाता है, maxLength/maximum कम करता है, enums को देखे गए मानों तक सीमित करता है।	हाँ — स्वीकृत मानों का दायरा कम करता है
जोड़ें	MISSING_CONSTRAINT	API एक ऐसा कंस्ट्रेंट लागू करता है जो स्पेक में प्रलेखित नहीं है। स्कीमा में कंस्ट्रेंट जोड़ता है।	हाँ — नया कंस्ट्रेंट जोड़ता है
हटाएं	EXTRA_CONSTRAINT	स्पेक एक ऐसा कंस्ट्रेंट घोषित करता है जिसे API अनदेखा करता है। स्कीमा से कंस्ट्रेंट हटाता है।	हाँ — कंस्ट्रेंट हटाता है

सावधानी

कंस्ट्रेंट सुधार API अनुबंध को बदलते हैं। ये केवल तभी लागू किए जाते हैं जब लाइव API के विरुद्ध Schemathesis या कंस्ट्रेंट सत्यापन परीक्षण से साक्ष्य द्वारा समर्थित हों।

समर्थित कंस्ट्रेंट प्रकार

परीक्षित और सुधारी जाने वाली 10 OpenAPI कंस्ट्रेंट श्रेणियाँ:

• स्ट्रिंग लंबाई — minLength, maxLength
• पैटर्न — pattern (regex)
• संख्यात्मक सीमाएं — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• आवश्यक फ़ील्ड — required
• Enum मान — enum
• ऐरे सीमाएं — minItems, maxItems, uniqueItems
• ऑब्जेक्ट संरचना — additionalProperties, properties, propertyNames
• कम्पोज़िशन — oneOf, anyOf, allOf
• डिपेंडेंसीज़ — dependentRequired, dependentSchemas
• डेटा प्रकार — type, format

Spectral संवर्धन

ये सुधार Spectral लिंटिंग द्वारा पाई गई OAS3 गुणवत्ता समस्याओं को संबोधित करते हैं। ये API व्यवहार को बदले बिना मेटाडेटा जोड़ते या सुधारते हैं।

सर्वर्स ब्लॉक इंजेक्शन

नियम: oas3-api-servers | अनुबंध परिवर्तन: नहीं

उन स्पेक्स में F5 XC टेनेंट URL टेम्पलेट जोड़ता है जिनमें servers ब्लॉक अनुपस्थित है:

"servers": [{
  "url": "https://{tenant}.console.ves.volterra.io",
  "description": "F5 Distributed Cloud API",
  "variables": {
    "tenant": {
      "default": "example-tenant",
      "description": "Your F5 XC tenant name"
    }
  }
}]

सर्वर URL और वेरिएबल मान validation.yaml में spectral.servers से आते हैं।

संपर्क जानकारी इंजेक्शन

नियम: info-contact | अनुबंध परिवर्तन: नहीं

उन स्पेक्स के लिए info.contact में संपर्क जानकारी जोड़ता है जिनमें यह अनुपस्थित है:

"contact": {
  "name": "F5 Distributed Cloud",
  "url": "https://docs.cloud.f5.com",
  "email": "support@f5.com"
}

मान validation.yaml में spectral.contact से आते हैं।

ऑपरेशन टैग व्युत्पत्ति

नियम: operation-tags | अनुबंध परिवर्तन: नहीं

बिना टैग वाले ऑपरेशनों के लिए URL पथ उपसर्ग से एक टैग प्राप्त करता है। /api/config/namespaces/{namespace}/healthchecks जैसे पथ के लिए, टैग config होता है (दूसरा गैर-पैरामीटर सेगमेंट)। टैग ऑपरेशन के tags ऐरे और स्पेक-स्तरीय tags सूची दोनों में जोड़ा जाता है।

अप्रयुक्त कंपोनेंट हटाना

नियम: oas3-unused-component | अनुबंध परिवर्तन: नहीं

components.schemas से उन कंपोनेंट स्कीमा को हटाता है जो स्पेक में कहीं भी संदर्भित नहीं हैं। किसी भी ऑपरेशन को प्रभावित किए बिना स्पेक का आकार कम करता है।

OperationId डिडुप्लिकेशन

नियम: operation-operationId-unique | अनुबंध परिवर्तन: नहीं

जब कई ऑपरेशन एक ही operationId साझा करते हैं तो HTTP मेथड को प्रत्यय के रूप में जोड़ता है (जैसे, ListItems_get)। यह कोड जनरेटर के लिए प्रत्येक operationId को अद्वितीय बनाता है।

अमान्य उदाहरण/डिफ़ॉल्ट हटाना

नियम: oas3-valid-schema-example | अनुबंध परिवर्तन: नहीं

स्कीमा से example या default मानों को हटाता है जब मान स्कीमा के अपने कंस्ट्रेंट्स (गलत प्रकार, सीमा से बाहर, आदि) के अनुरूप नहीं होता। कोड जनरेटर को अमान्य नमूना पेलोड उत्पन्न करने से रोकता है।

स्क्रिप्ट टैग स्ट्रिपिंग

नियम: no-script-tags-in-markdown | अनुबंध परिवर्तन: नहीं

regex प्रतिस्थापन का उपयोग करके description फ़ील्ड से <script> टैग हटाता है। कुछ अपस्ट्रीम स्पेक्स में इंजेक्ट किए गए स्क्रिप्ट टैग होते हैं जो दस्तावेज़ीकरण रेंडरर को तोड़ देते हैं।

सुरक्षा मेटाडेटा

अनुबंध परिवर्तन: नहीं (केवल दस्तावेज़ीकरण)

प्रत्येक स्पेक को एक apiKeyAuth सुरक्षा योजना प्राप्त होती है यदि पहले से मौजूद नहीं है। यह हमेशा इंजेक्ट किया जाता है, चाहे Spectral ने इसे फ़्लैग किया हो या नहीं।

"components": {
  "securitySchemes": {
    "apiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "F5 XC API Token (format: APIToken <token>)"
    }
  }
},
"security": [{ "apiKeyAuth": [] }]

योजना परिभाषा validation.yaml में spectral.security_scheme से आती है। यह API उपभोक्ताओं को प्रमाणीकरण का तरीका बताता है लेकिन रनटाइम व्यवहार नहीं बदलता।

JSON फ़ॉर्मेटिंग

अनुबंध परिवर्तन: नहीं

सभी आउटपुट JSON स्पेक्स Biome-संगत ऐरे कॉम्पैक्टर (scripts/utils/spec_loader.py में _compact_short_arrays) से गुज़रते हैं। 120 अक्षरों के भीतर आने वाले छोटे ऐरे एकल पंक्ति में संक्षिप्त किए जाते हैं:

// Before
"enum": [
  "ACTIVE",
  "INACTIVE"
]

// After
"enum": ["ACTIVE", "INACTIVE"]

पंक्ति-लंबाई सीमा से अधिक वाले ऐरे बहु-पंक्ति रहते हैं।

सुधार प्राथमिकता

जब कई सुधार रणनीतियाँ लागू हो सकती हैं, तो रिकंसाइलर reconciliation.priority में कॉन्फ़िगर की गई प्राथमिकता क्रम का उपयोग करता है:

1. existing — यदि मान्य है तो मौजूदा स्पेक कंस्ट्रेंट का उपयोग करें
2. discovery — खोजे गए लाइव API व्यवहार का उपयोग करें
3. inferred — समान एंडपॉइंट्स के पैटर्न से अनुमान लगाएं

सभी सुधार लागू होने के बाद प्रत्येक सुधारे गए स्पेक को openapi-spec-validator से सत्यापित किया जाता है। यदि सत्यापन विफल होता है, तो मूल स्पेक को फ़ॉलबैक के रूप में उपयोग किया जाता है और सुधार को त्रुटि के रूप में लॉग किया जाता है।