विकास गाइड

यह गाइड F5 XC API संवर्धन पाइपलाइन के लिए विकास वर्कफ़्लो का वर्णन करती है।

त्वरित प्रारंभ

प्रथम बार सेटअप

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

पाइपलाइन प्रवाह

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

डायरेक्टरी संरचना

डायरेक्टरी	उद्देश्य	Git स्थिति
specs/original/	F5 स्रोत specs	Gitignored
specs/discovered/	API खोज आउटपुट	Tracked (openapi.json, session.json)
docs/specifications/api/	जनरेट किए गए डोमेन specs	Gitignored
scripts/	Python पाइपलाइन स्क्रिप्ट	Tracked
config/	पाइपलाइन कॉन्फ़िगरेशन	Tracked
reports/	जनरेट की गई रिपोर्ट	Gitignored

वर्कफ़्लो पैटर्न

1. खोज वर्कफ़्लो

पूर्वापेक्षाएँ:

• F5 XC परिवेश से VPN कनेक्शन
• वैध 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 मान
• डिफ़ॉल्ट मान
• पैटर्न सत्यापन
• प्रतिक्रिया उदाहरण

2. रिलीज़ वर्कफ़्लो

रिलीज़ स्वचालित हैं:

1. दैनिक शेड्यूल (6 AM UTC) या मुख्य शाखा पर push वर्कफ़्लो ट्रिगर करता है
2. ETag जाँच निर्धारित करती है कि F5 specs बदले हैं या नहीं
3. पाइपलाइन specs को प्रोसेस और संवर्धित करती है
4. संस्करण git tags से परिकलित: git describe --tags --abbrev=0
5. डायरेक्ट commit + tag बनाया जाता है (कोई version bump PR नहीं)
6. changelog के साथ GitHub Release बनाई जाती है
7. दस्तावेज़ीकरण GitHub Pages पर तैनात होता है

संस्करण बम्प नियम:

शर्त	बम्प प्रकार	उदाहरण
commit में [major]	Major	1.0.0 → 2.0.0
commit में BREAKING CHANGE	Major	1.0.0 → 2.0.0
नया डोमेन 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

खोज एक्सटेंशन

खोज specs में x-discovered-* एक्सटेंशन जोड़ती है:

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

कॉन्फ़िगरेशन गाइड

संवर्धन कॉन्फ़िगरेशन

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

सामान्यीकरण कॉन्फ़िगरेशन

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

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

config/spectral.yaml

extends:
  - spectral:oas

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

OpenAPI एक्सटेंशन

संवर्धन पाइपलाइन सत्यापन और डिफ़ॉल्ट मान मेटाडेटा एम्बेड करने के लिए vendor एक्सटेंशन का उपयोग करती है।

एक्सटेंशन श्रेणियाँ

एक्सटेंशन	अर्थ	निहितार्थ
x-f5xc-server-default	F5 XC API सर्वर फ़ील्ड छोड़ने पर यह मान लागू करता है	फ़ील्ड वैकल्पिक है; इसे छोड़ने पर दस्तावेज़ित डिफ़ॉल्ट व्यवहार प्राप्त होता है
x-f5xc-recommended-value	F5 XC वेब कंसोल नए संसाधनों के लिए इस मान को पूर्व-भरता है	फ़ील्ड का कोई सर्वर डिफ़ॉल्ट नहीं है, लेकिन यह मान विशिष्ट कॉन्फ़िगरेशन का प्रतिनिधित्व करता है
x-f5xc-recommended-oneof-variant	F5 XC कंसोल इस OneOf वेरिएंट को पूर्व-चयनित करता है	एकाधिक परस्पर अनन्य विकल्पों में से विशिष्ट चुनाव की पहचान करता है
x-f5xc-conflicts-with	अन्य गुण सूचीबद्ध करता है जिन्हें इस फ़ील्ड के साथ उपयोग नहीं किया जा सकता	गुण OneOf समूह का हिस्सा है; विरोधाभासी गुणों में से केवल एक निर्दिष्ट किया जा सकता है

आवश्यक फ़ील्ड एक्सटेंशन

एक्सटेंशन	स्रोत	उद्देश्य
x-ves-required: "true"	F5 XC मूल spec	फ़ील्ड के लिए गैर-शून्य/गैर-रिक्त मान आवश्यक है
x-f5xc-required-for	संवर्धन पाइपलाइन	संदर्भ-विशिष्ट आवश्यक स्थिति

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 वेरिएंट
x-f5xc-conflicts-with	अन्य OneOf गुणों के साथ परस्पर अनन्यता

x-f5xc-server-default

प्रकार: boolean

जब true हो, तो यह इंगित करता है कि साथ में दिया गया default मान F5 XC API सर्वर द्वारा लागू किया जाता है। इस एक्सटेंशन वाले फ़ील्ड को API अनुरोधों से सुरक्षित रूप से छोड़ा जा सकता है — सर्वर स्वचालित रूप से डिफ़ॉल्ट लागू करता है।

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

x-f5xc-recommended-value

प्रकार: any (फ़ील्ड प्रकार से मेल खाता है)

एक ऐसा मान निर्दिष्ट करता है जिसे F5 XC वेब कंसोल पूर्व-भरित डिफ़ॉल्ट के रूप में उपयोग करता है। यह मान सर्वर द्वारा लागू नहीं होता, लेकिन कंसोल के माध्यम से बनाए गए नए संसाधनों के लिए विशिष्ट प्रारंभिक कॉन्फ़िगरेशन का प्रतिनिधित्व करता है।

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

x-f5xc-recommended-oneof-variant

प्रकार: object (समूह नाम से वेरिएंट नाम का मैप)

परस्पर अनन्य फ़ील्ड समूहों वाले schemas के लिए, पहचानता है कि कौन सा वेरिएंट डिफ़ॉल्ट या सबसे सामान्य विकल्प है। कुंजी OneOf समूह का नाम है और मान अनुशंसित वेरिएंट फ़ील्ड नाम है।

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

x-f5xc-conflicts-with

प्रकार: strings की array

जोड़ा गया: v3.2.0 (Issue #494)

OneOf समूह सदस्यों के बीच परस्पर अनन्यता संबंध घोषित करता है। x-ves-oneof-field-* एक्सटेंशन से स्वतः-व्युत्पन्न। यह डाउनस्ट्रीम उपकरणों (Terraform, CLI, MCP) को रनटाइम के बजाय schema स्तर पर विरोधाभासों को सत्यापित करने में सक्षम बनाता है।

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 प्रोवाइडर सत्यापन नियम उत्पन्न कर सकते हैं
• CLI उपकरण विरोधाभासी फ़ील्ड संयोजनों के बारे में चेतावनी दे सकते हैं
• AI सहायक सही OneOf कॉन्फ़िगरेशन उत्पन्न कर सकते हैं
• IDE एक्सटेंशन विरोध-सचेत स्वतः-पूर्णता प्रदान कर सकते हैं

स्रोत: पाइपलाइन संवर्धन के दौरान F5 नेटिव x-ves-oneof-field-* एक्सटेंशन से स्वतः-व्युत्पन्न।

सत्यापन नियम निहितार्थ

संवर्धनकर्ता आवश्यक स्थिति अनुमानित करने के लिए 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 चाहिए

सर्वर-लागू डिफ़ॉल्ट वाले संसाधन

कुछ संसाधन खाली specs स्वीकार करते हैं क्योंकि सर्वर डिफ़ॉल्ट लागू करता है:

संसाधन	सर्वर-लागू डिफ़ॉल्ट
app_firewall	monitoring: \{\}, default_detection_settings: \{\}
rate_limiter	limits: [], user_identification: []
api_definition	swagger_specs: [], डिफ़ॉल्ट api_groups
healthcheck	jitter: 0, jitter_percent: 0, नेस्टेड http_health_check डिफ़ॉल्ट

इन संसाधनों के लिए, 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. API के माध्यम से न्यूनतम spec के साथ F5 XC में संसाधन बनाएँ
2. सर्वर-लागू मान देखने के लिए संसाधन वापस पढ़ें
3. config/discovered_defaults.yaml में डिफ़ॉल्ट दस्तावेज़ित करें
4. पाइपलाइन चलाएँ: make pipeline
5. सत्यापित करें: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

समस्या निवारण

Pre-commit बहुत अधिक समय लेता है

पाइपलाइन प्रत्येक commit पर संगतता सुनिश्चित करने के लिए चलती है। कार्य-प्रगति commits के लिए:

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

जनरेट किए गए Specs पर Lint त्रुटियाँ

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

आउटपुट फ़ाइलों में नहीं, बल्कि संवर्धन/सामान्यीकरण कॉन्फ़िगरेशन में समस्याएँ ठीक करें।

संस्करण प्रणाली

संस्करण git tags से व्युत्पन्न होता है (जैसे v2.0.38), जो एक साथ चलने वाले PRs पर merge conflicts उत्पन्न करने वाली race conditions को समाप्त करता है।

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

Clone के बाद Specs गायब हैं

जनरेट किए गए specs gitignored हैं:

make build  # Downloads and generates everything

बड़ी फ़ाइल अवरुद्ध हुई

.pre-commit-config.yaml में अपवाद जोड़ें:

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

त्वरित संदर्भ

Make लक्ष्य

लक्ष्य	विवरण
make build	पूर्ण निर्माण (download + pipeline)
make rebuild	त्वरित पुनर्निर्माण (download छोड़ें)
make download	Specs डाउनलोड करें (ETag cached)
make download-force	जबरदस्ती डाउनलोड करें
make pipeline	संवर्धन पाइपलाइन चलाएँ
make lint	Spectral लिंटिंग
make serve	स्थानीय दस्तावेज़ीकरण सर्वर
make discover	API खोज (VPN आवश्यक)
make push-discovery	खोज डेटा commit करें
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	संवर्धन नियम
config/normalization.yaml	सामान्यीकरण नियम
config/discovery.yaml	खोज सेटिंग
config/spectral.yaml	लिंटिंग नियम
scripts/utils/version_calculator.py	Tag-आधारित संस्करण परिकलन

नोट: संस्करण .version फ़ाइल से नहीं, बल्कि git tags से व्युत्पन्न होता है (जैसे v2.0.38)।