{"id":34532341,"url":"https://github.com/robinmordasiewicz/f5xc-api-enriched","last_synced_at":"2026-04-04T08:03:16.810Z","repository":{"id":329530430,"uuid":"1119195176","full_name":"robinmordasiewicz/f5xc-api-enriched","owner":"robinmordasiewicz","description":"Enriched F5 Distributed Cloud OpenAPI specifications with CLI metadata","archived":false,"fork":false,"pushed_at":"2026-03-04T06:23:55.000Z","size":84103,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T13:08:06.795Z","etag":null,"topics":["api","f5xc","openapi"],"latest_commit_sha":null,"homepage":"https://robinmordasiewicz.github.io/f5xc-api-enriched/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robinmordasiewicz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-18T22:37:22.000Z","updated_at":"2026-03-04T12:13:26.000Z","dependencies_parsed_at":"2026-01-20T09:00:32.289Z","dependency_job_id":null,"html_url":"https://github.com/robinmordasiewicz/f5xc-api-enriched","commit_stats":null,"previous_names":["robinmordasiewicz/f5xc-api-enriched"],"tags_count":171,"template":false,"template_full_name":null,"purl":"pkg:github/robinmordasiewicz/f5xc-api-enriched","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinmordasiewicz%2Ff5xc-api-enriched","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinmordasiewicz%2Ff5xc-api-enriched/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinmordasiewicz%2Ff5xc-api-enriched/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinmordasiewicz%2Ff5xc-api-enriched/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robinmordasiewicz","download_url":"https://codeload.github.com/robinmordasiewicz/f5xc-api-enriched/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinmordasiewicz%2Ff5xc-api-enriched/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","f5xc","openapi"],"created_at":"2025-12-24T05:50:28.196Z","updated_at":"2026-03-07T08:05:13.890Z","avatar_url":"https://github.com/robinmordasiewicz.png","language":"Python","readme":"# f5xc-api-enriched\n\nAutomated OpenAPI enrichment pipeline for F5 Distributed Cloud API specifications, enhancing developer experience with comprehensive descriptions, metadata, and standardized extensions.\n\n## Overview\n\nThis repository transforms F5 Distributed Cloud's 270+ OpenAPI specifications into enriched, developer-friendly documentation with:\n\n- **100% Description Coverage**: All 32,141 describable properties have meaningful descriptions\n- **DRY-Compliant Content**: Pattern-based generation preventing redundant information\n- **Multi-Tier Descriptions**: Short (≤60 chars), medium (≤150 chars), long (≤500 chars) for different use cases\n- **Standardized Extensions**: Custom OpenAPI extensions for metadata, configuration, and tooling integration\n\n## Key Features\n\n### Description Enrichment\n\n- **Property Descriptions**: 32,141 properties with full descriptions (100% coverage)\n- **Short Descriptions**: 21,422 properties with CLI-optimized descriptions (37.8% coverage)\n- **Domain Descriptions**: 270+ specifications with 3-tier descriptions (short/medium/long)\n- **Operation Descriptions**: DRY-compliant, noun-first descriptions for API operations\n- **Pattern System**: 140+ field patterns + 80+ short description patterns + 8 operation patterns\n\n### Metadata Enrichment\n\n- **Configuration Metadata**: Minimum configurations for 90+ resources (5 explicit + auto-generated)\n- **Operation Metadata**: Danger levels, required fields, side effects for all operations\n- **Resource Metadata**: Rich metadata for tooling integration\n- **Best Practices**: Domain-specific operational knowledge and guided workflows\n- **Acronym Expansion**: 450+ industry acronyms and F5-specific terminology\n\n### Quality \u0026 Validation\n\n- **99% Meaningful Descriptions**: Not generic fallbacks\n- **DRY Compliance**: 5-layer validation preventing redundant content\n- **Character Limits**: Enforced limits for each description tier\n- **Grammar Enhancement**: Automated grammar correction for technical writing\n- **Consistency Validation**: Cross-specification validation\n\n## Architecture\n\n### Pipeline Stages\n\n```text\n1. Download    → GitHub Releases (version-cached spec retrieval)\n2. Enrich      → Descriptions, branding, grammar, metadata\n3. Normalize   → Schema references, type fixes, consistency\n4. Merge       → Domain-specific spec generation\n5. Validate    → Spectral linting + live API validation\n6. Deploy      → GitHub Pages (Starlight docs)\n```\n\n### Enrichment Pipeline (17 Steps)\n\n| Step | Enricher | Purpose |\n|------|----------|---------|\n| 1 | SchemaFixer | Fix invalid schemas and missing components |\n| 2 | BrandingTransformer | Branding consistency |\n| 3 | TagGenerator | Generate operation tags from paths |\n| 4 | DescriptionEnricher | Domain descriptions (short/medium/long) |\n| 5 | FieldDescriptionEnricher | Property descriptions (140+ patterns) |\n| 6 | GrammarImprover | Automated grammar correction |\n| 7 | DescriptionValidator | DRY compliance, quality validation |\n| 8 | DescriptionStructureTransformer | Convert block quotes to proper structure |\n| 9 | AcronymEnricher | Add acronym definitions to specs |\n| 10 | PropertyDescriptionShortEnricher | CLI-optimized short descriptions (80+ patterns) |\n| 11 | ResourceExamplesEnricher | Add tiered resource examples |\n| 12 | FieldMetadataEnricher | Add field-level metadata |\n| 13 | ValidationEnricher | Add validation rules and patterns |\n| 14 | **OperationDescriptionEnricher** | **DRY-compliant operation descriptions** |\n| 15 | OperationMetadataEnricher | Danger levels, required fields, side effects |\n| 16 | MinimumConfigurationEnricher | Minimum viable configurations |\n| 17 | ReadOnlyEnricher | Mark API-computed fields as readOnly |\n\n### Discovery \u0026 Reconciliation (VPN Required)\n\nLive API exploration to discover undocumented behavior:\n\n```bash\nexport F5XC_API_URL=\"https://tenant.console.ves.volterra.io/api\"\nexport F5XC_API_TOKEN=\"your-api-token\"\nmake discover              # Explore live API\nmake push-discovery        # Commit discovery data for CI/CD\n```\n\n**Discovery Features**:\n\n- Tighter constraints detection (e.g., API enforces maxLength:63 vs spec allows 1024)\n- New undocumented constraints (pattern validation, enum restrictions)\n- Response time profiling (p50/p95/p99 latencies)\n- Rate limiting behavior\n- Undocumented fields\n\n### GitHub Release Integration\n\nAPI specifications are sourced from **[robinmordasiewicz/f5xc-api-fixed](https://github.com/robinmordasiewicz/f5xc-api-fixed)** via GitHub Releases.\n\n**Benefits**:\n- Pre-validated specs (268 domain specs, 5.7 MB compressed)\n- Version-based caching (faster than HTTP ETag)\n- Full control via source repository\n- Easy rollback to any release\n\n**Authentication** (optional but recommended):\n```bash\n# Set GitHub token for higher rate limits (5000/hr vs 60/hr)\nexport GITHUB_TOKEN=\"ghp_your_personal_access_token\"\n```\n\n**Release Format**:\n- Versioning: `vYYYY.MM.DD-N` (date-based with sequence)\n- Asset: `f5xc-api-fixed-v{version}.zip`\n- Contents: `domains/*.json` (268 domain specifications)\n\n**CI/CD**: GitHub Actions automatically uses `secrets.GITHUB_TOKEN` for authentication.\n\n## Quick Start\n\n### Prerequisites\n\n```bash\n# Python 3.11+ required\npython --version\n\n# Install dependencies\nmake install\n\n# Install pre-commit hooks (runs full pipeline on every commit)\nmake pre-commit-install\n```\n\n### Basic Usage\n\n```bash\n# Full pipeline (download → enrich → normalize → merge)\nmake build\n\n# Quick rebuild (skip download, use existing specs)\nmake rebuild\n\n# Individual stages\nmake download       # Fetch latest F5 specs from GitHub Releases (version cached)\nmake pipeline       # Run enrichment pipeline\nmake lint           # Spectral OpenAPI linting\nmake validate       # Test curl examples against live API\n\n# Development\nmake serve          # Serve docs locally (http://localhost:8000)\nmake clean          # Remove generated files\n```\n\n### CI/CD Integration\n\nThe repository uses GitHub Actions for automated releases:\n\n```yaml\nTrigger: Daily schedule, push to main, manual dispatch\nProcess:\n  1. Check for spec updates (GitHub release version comparison)\n  2. Download changed specs\n  3. Run enrichment pipeline\n  4. Validate with Spectral + live API\n  5. Auto-version (semantic versioning)\n  6. Create GitHub release\n  7. Deploy to GitHub Pages\n```\n\n**Version Bumping**:\n\n- New API domains → **Minor** version (e.g., 1.0.15 → 1.1.0)\n- Spec updates (no new domains) → **Patch** version (e.g., 1.0.15 → 1.0.16)\n- Pipeline/config changes → **Patch** version\n- Breaking changes → **Major** version (commit message: `[major]` or `BREAKING CHANGE`)\n\n## Operation Description System\n\n### Problem: Redundant Descriptions\n\n**Before** (verb-first, redundant):\n\n```yaml\n# Command: \u003ctool\u003e \u003cdomain\u003e create \u003cresource\u003e\nx-f5xc-operation-metadata:\n  purpose: \"Create new http_loadbalancer\"  # ❌ Redundant - user typed \"create\"\n```\n\n**After** (noun-first, DRY-compliant):\n\n```yaml\n# Command: \u003ctool\u003e \u003cdomain\u003e create \u003cresource\u003e\nx-f5xc-operation-metadata:\n  purpose: \"HTTP/HTTPS load balancer with origin pools and routing rules\"  # ✅\n```\n\n### Three-Tier Matching Strategy\n\n```text\n1. Exact Match: \"http_loadbalancer\" → explicit description\n2. Pattern Match: \".*loadbalancer.*\" → pattern-based description\n3. Method Fallback: POST → \"Resource creation operation\"\n```\n\n### Configuration\n\n`config/operation_descriptions.yaml`:\n\n- 10 high-priority resources (explicit descriptions)\n- 8 pattern matchers (regex-based matching)\n- 5 HTTP method fallbacks (POST/GET/PUT/PATCH/DELETE)\n\n## Using Enriched Specifications\n\n### Accessing Extensions\n\nThe enriched specifications include custom OpenAPI extensions in the `x-f5xc-*` namespace. These extensions provide metadata for building tools, CLI interfaces, and AI assistants.\n\n#### Operation Metadata\n\nAccess operation-level metadata for command interfaces:\n\n```javascript\n// JavaScript/TypeScript example\nconst operation = spec.paths[\"/api/config/namespaces/{namespace}/http_loadbalancers\"][\"post\"];\nconst metadata = operation[\"x-f5xc-operation-metadata\"];\n\nconsole.log(metadata.purpose);          // \"HTTP/HTTPS load balancer with origin pools...\"\nconsole.log(metadata.danger_level);     // \"medium\"\nconsole.log(metadata.required_fields);  // [\"metadata.name\", \"metadata.namespace\"]\n```\n\n```python\n# Python example\noperation = spec[\"paths\"][\"/api/config/namespaces/{namespace}/http_loadbalancers\"][\"post\"]\nmetadata = operation.get(\"x-f5xc-operation-metadata\", {})\n\nprint(metadata.get(\"purpose\"))          # \"HTTP/HTTPS load balancer with origin pools...\"\nprint(metadata.get(\"danger_level\"))     # \"medium\"\nprint(metadata.get(\"required_fields\"))  # [\"metadata.name\", \"metadata.namespace\"]\n```\n\n#### Minimum Configurations\n\nAccess minimum viable configurations for resource creation:\n\n```javascript\n// JavaScript/TypeScript example\nconst schema = spec.components.schemas[\"HttpLoadBalancerCreateRequest\"];\nconst minConfig = schema[\"x-f5xc-minimum-configuration\"];\n\nconsole.log(minConfig.description);     // Minimum configuration description\nconsole.log(minConfig.required_fields); // [\"metadata.name\", \"metadata.namespace\"]\nconsole.log(minConfig.example_yaml);    // YAML configuration template\n```\n\n```python\n# Python example\nschema = spec[\"components\"][\"schemas\"][\"HttpLoadBalancerCreateRequest\"]\nmin_config = schema.get(\"x-f5xc-minimum-configuration\", {})\n\nprint(min_config.get(\"description\"))     # Minimum configuration description\nprint(min_config.get(\"required_fields\")) # [\"metadata.name\", \"metadata.namespace\"]\nprint(min_config.get(\"example_yaml\"))    # YAML configuration template\n```\n\n#### Resource Metadata\n\nAccess rich resource metadata from the specification index:\n\n```javascript\n// JavaScript/TypeScript example\nconst index = await fetch(\"https://robinmordasiewicz.github.io/f5xc-api-enriched/specifications/index.json\");\nconst data = await index.json();\n\nconst resource = data.primary_resources.find(r =\u003e r.name === \"http_loadbalancer\");\nconsole.log(resource.description);       // Full resource description\nconsole.log(resource.tier);              // \"Standard\"\nconsole.log(resource.dependencies);      // {required: [\"origin_pool\"], optional: [...]}\n```\n\n```python\n# Python example\nimport requests\n\nresponse = requests.get(\"https://robinmordasiewicz.github.io/f5xc-api-enriched/specifications/index.json\")\ndata = response.json()\n\nresource = next(r for r in data[\"primary_resources\"] if r[\"name\"] == \"http_loadbalancer\")\nprint(resource[\"description\"])       # Full resource description\nprint(resource[\"tier\"])              # \"Standard\"\nprint(resource[\"dependencies\"])      # {required: [\"origin_pool\"], optional: [...]}\n```\n\n### Multi-Tier Descriptions\n\nSpecifications include three description tiers optimized for different use cases:\n\n| Tier | Max Length | Use Case | Access Path |\n|------|-----------|----------|-------------|\n| `short` | 60 chars | CLI columns, tooltips | `property[\"x-f5xc-description-short\"]` |\n| `medium` | 150 chars | Help text, summaries | `spec.info[\"x-f5xc-description-medium\"]` |\n| `long` | 500 chars | Documentation, AI context | `property.description` |\n\n```javascript\n// Accessing description tiers\nconst property = schema.properties[\"origin_pool\"];\n\n// Short (CLI display)\nconst shortDesc = property[\"x-f5xc-description-short\"];  // \"Backend server pool\"\n\n// Long (full documentation)\nconst longDesc = property.description;  // \"Origin pool defines a collection of backend...\"\n```\n\n## Documentation\n\n### Published Documentation\n\n- **API Specs Index**: \u003chttps://robinmordasiewicz.github.io/f5xc-api-enriched/\u003e\n\n### Developer Documentation\n\n- **CLAUDE.md**: Comprehensive AI assistant instructions and technical details\n- **CHANGELOG.md**: Auto-generated release notes\n\n## Configuration Files and Extensions\n\n### Key Configuration Files\n\n| File | Purpose |\n|------|---------|\n| `config/enrichment.yaml` | Branding, acronyms, grammar rules |\n| `config/normalization.yaml` | Schema normalization rules |\n| `config/domain_descriptions.yaml` | Domain descriptions (3 tiers) |\n| `config/operation_descriptions.yaml` | Operation descriptions (DRY-compliant) |\n| `config/field_descriptions.yaml` | Field description patterns (140+) |\n| `config/property_description_short.yaml` | Short description patterns (80+) |\n| `config/minimum_configs.yaml` | Minimum viable configurations |\n| `config/resource_metadata.yaml` | Per-resource metadata (90+ resources) |\n| `config/extension_registry.yaml` | All x-f5xc-* extensions (50+) |\n\n### Extension Namespace\n\nAll custom extensions use the `x-f5xc-*` namespace:\n\n- **Spec-level**: `x-f5xc-cli-domain`, `x-f5xc-enriched-version`, `x-f5xc-glossary`\n- **Schema-level**: `x-f5xc-minimum-configuration`, `x-f5xc-display-name`, `x-f5xc-namespace-scope`\n- **Property-level**: `x-f5xc-description-short`, `x-f5xc-validation`, `x-f5xc-examples`\n- **Operation-level**: `x-f5xc-operation-metadata`, `x-f5xc-danger-level`, `x-f5xc-required-fields`\n\nSee `config/extension_registry.yaml` for complete documentation.\n\n## Multi-Environment Support\n\nThe specifications support multi-environment, multi-tenant deployments through server variables:\n\n```yaml\nservers:\n  - url: https://{tenant}.{console_url}/api/v1/namespaces/{namespace}\n    variables:\n      tenant: {default: \"example-corp\"}\n      console_url: {default: \"console.ves.volterra.io\"}\n      namespace: {default: \"default\"}\n```\n\n**Environment Variables**:\n\n- `F5XC_TENANT`: Tenant identifier\n- `F5XC_CONSOLE_URL`: Console URL base\n- `F5XC_DEFAULT_NAMESPACE`: Default namespace\n- `F5XC_ENVIRONMENT`: Environment designation (production/staging/development)\n- `F5XC_REGION`: Geographic region\n- `F5XC_DOMAIN_PREFIX`: Domain naming convention\n\n## Statistics\n\n### Coverage Metrics\n\n```text\nTotal Specifications: 270\nTotal Properties: 56,706\nProperties with Descriptions: 32,141 (56.7% - 100% of describable)\nProperties with Short Descriptions: 21,422 (37.8%)\n$ref Properties: 24,565 (appropriately excluded)\nQuality Score: 99% meaningful descriptions\n```\n\n### Pipeline Performance\n\n```text\nAverage Processing Time: ~2 minutes (270 specs)\nPeak Memory Usage: 154 MB\nCache Hit Rate: ~85% (GitHub release version-based)\nParallel Batch Processing: 14 batches\nDiscovery Enrichment: 1,239,194 constraints reconciled\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# All tests\npytest\n\n# Specific test suites\npytest tests/test_operation_description_enricher.py -v\npytest tests/test_deprecated_tier_enricher.py -v\n\n# With coverage\npytest --cov=scripts --cov-report=html\n```\n\n### Pre-commit Hooks\n\nThe repository uses pre-commit hooks that run on every commit:\n\n```yaml\nHooks:\n  - F5 XC API Enrichment Pipeline (full rebuild)\n  - Spectral linting (all 270+ specs)\n  - Ruff (linting + formatting)\n  - MyPy (type checking)\n  - Security checks (gitleaks, detect-private-key)\n  - File hygiene (trailing whitespace, line endings)\n```\n\n**Note**: Every commit triggers a full pipeline run (~50 seconds). This ensures specification consistency.\n\n### Contributing\n\n1. Create feature branch: `git checkout -b feature/issue-XXX-description`\n2. Make changes\n3. Commit (pre-commit hooks will run automatically)\n4. Push and create PR\n5. CI/CD will validate and auto-merge if approved\n\n## License\n\nMIT License - Copyright (c) 2026 Robin Mordasiewicz\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/robinmordasiewicz/f5xc-api-enriched/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/robinmordasiewicz/f5xc-api-enriched/discussions)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinmordasiewicz%2Ff5xc-api-enriched","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobinmordasiewicz%2Ff5xc-api-enriched","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinmordasiewicz%2Ff5xc-api-enriched/lists"}