Spectral लिंटिंग नियम

यह प्रोजेक्ट OAS3 लिंटिंग के लिए Spectral का उपयोग करता है, जिसमें दो-कॉन्फ़िग आर्किटेक्चर है जो CI/बाहरी टूलिंग को पाइपलाइन की कस्टम लॉजिक से अलग करता है।

दो-कॉन्फ़िग आर्किटेक्चर

.spectral.yaml — बेस कॉन्फ़िग

GitHub Super-Linter और किसी भी बाहरी CI टूल द्वारा उपयोग किया जाता है। spectral:oas (बिल्ट-इन OAS रूलसेट) को एक्सटेंड करता है। इसमें कोई कस्टम फ़ंक्शन नहीं है — यह इसे उन टूल्स के साथ संगत रखता है जो spectral/functions/ डायरेक्टरी तक पहुँच के बिना Spectral चलाते हैं।

extends:
  - "spectral:oas"

rules:
  path-params: "off"
  operation-tags: warn
  oas3-api-servers: warn
  info-contact: warn
  oas3-unused-component: warn
  operation-operationId-unique: error
  oas3-valid-schema-example: error
  no-script-tags-in-markdown: warn
  operation-description: info
  info-description: info

spectral-pipeline.yaml — पाइपलाइन कॉन्फ़िग

scripts/spectral_lint.py (discover और gate दोनों मोड) द्वारा उपयोग किया जाता है। बेस कॉन्फ़िग को एक्सटेंड करता है और कस्टम f5-path-params फ़ंक्शन जोड़ता है:

extends:
  - "./.spectral.yaml"

functionsDir: "./spectral/functions"
functions:
  - f5-path-params

rules:
  f5-path-params:
    description: "Path parameters must be declared and used"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: f5-path-params

path-params क्यों अक्षम है

Spectral का बिल्ट-इन path-params नियम F5 XC API को गलत तरीके से फ़्लैग करता है जो {metadata.namespace} और {metadata.name} जैसे डॉटेड पैरामीटर नामों का उपयोग करते हैं। बिल्ट-इन नियम पैरामीटर नामों में डॉट्स को पार्स नहीं करता, इसलिए यह उन्हें अघोषित के रूप में रिपोर्ट करता है।

कस्टम f5-path-params फ़ंक्शन (spectral/functions/f5-path-params.js) पूर्ण {placeholder} सामग्री को घोषित पैरामीटर नामों के विरुद्ध मिलान करके डॉटेड नामों को सही ढंग से संभालता है। यह पाथ-लेवल और ऑपरेशन-लेवल दोनों पैरामीटर की जाँच करता है, और दोनों दिशाओं में त्रुटियाँ रिपोर्ट करता है:

• URL पाथ में एक प्लेसहोल्डर जिसका कोई मेल खाता पैरामीटर घोषणा नहीं है
• एक घोषित पाथ पैरामीटर जो URL पाथ में दिखाई नहीं देता

नियम संदर्भ

स्वत: सुधार योग्य नियम

जब उल्लंघन पाए जाते हैं तो इन नियमों को रिकॉन्साइलर द्वारा स्वचालित रूप से ठीक किया जाता है। प्रत्येक सुधार के विवरण के लिए लागू किए गए सुधार देखें।

नियम	गंभीरता	सुधार विधि	विवरण
oas3-api-servers	warn	_add_servers	स्पेक में servers ब्लॉक होना चाहिए
info-contact	warn	_add_contact	info में contact शामिल होना चाहिए
operation-tags	warn	_add_tags	प्रत्येक ऑपरेशन में कम से कम एक टैग होना चाहिए
oas3-unused-component	warn	_remove_unused_component	कोई अनसंदर्भित कम्पोनेंट स्कीमा नहीं
operation-operationId-unique	error	_deduplicate_operation_id	सभी operationId अद्वितीय होने चाहिए
oas3-valid-schema-example	error	_fix_schema_example	उदाहरण/डिफ़ॉल्ट अपने स्कीमा से मेल खाने चाहिए
no-script-tags-in-markdown	warn	_strip_script_tags	विवरणों में <script> टैग नहीं होने चाहिए
f5-path-params	error	—	पाथ पैरामीटर घोषित और उपयोग किए जाने चाहिए

टिप्पणी

f5-path-params एक error-गंभीरता वाला नियम है लेकिन स्वत: सुधार नहीं किया जाता। उल्लंघन एक वास्तविक स्पेक दोष को इंगित करते हैं जिसके लिए मैन्युअल समीक्षा आवश्यक है।

सुधार अयोग्य नियम

इन नियमों को info गंभीरता में डाउनग्रेड किया गया है क्योंकि इन्हें सार्थक रूप से स्वचालित सुधार नहीं किया जा सकता:

नियम	गंभीरता	विवरण
operation-description	info	ऑपरेशन में विवरण होना चाहिए
info-description	info	API जानकारी में विवरण होना चाहिए

पाइपलाइन एकीकरण

Spectral एडाप्टर (scripts/spectral_lint.py) दो मोड में चलता है:

डिस्कवर मोड (रिकॉन्साइल से पहले)

make spectral-lint
# Equivalent to: python -m scripts.spectral_lint --mode discover

specs/original/ को स्कैन करता है और reports/spectral_report.json लिखता है। रिकॉन्साइलर इस रिपोर्ट को वैलिडेशन रिपोर्ट के साथ उपयोग करता है।

गेट मोड (रिकॉन्साइल के बाद)

make spectral-gate
# Equivalent to: python -m scripts.spectral_lint --mode gate

release/specs/ को स्कैन करता है और reports/spectral_gate_report.json लिखता है। यदि उल्लंघन कॉन्फ़िगर की गई सीमाओं से अधिक हों तो एग्ज़िट कोड 1 लौटाता है।

उल्लंघन मैपिंग

Spectral उल्लंघनों को तीन उपप्रकारों के साथ Discrepancy ऑब्जेक्ट में परिवर्तित किया जाता है:

Spectral नियम श्रेणी	DiscrepancyType	उदाहरण नियम
आवश्यक तत्व गायब	SPECTRAL_MISSING	oas3-api-servers, info-contact, operation-tags
अमान्य मौजूदा तत्व	SPECTRAL_INVALID	oas3-valid-schema-example, no-script-tags-in-markdown
अप्रयुक्त कोड	SPECTRAL_UNUSED	oas3-unused-component