Entwicklungshandbuch

Dieses Handbuch beschreibt den Entwicklungsworkflow für die F5 XC API-Anreicherungspipeline.

Schnellstart

Erstmalige Einrichtung

# 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

Tägliche Entwicklung

# Quick rebuild (uses cached specs)
make rebuild

# Run all quality checks
make pre-commit-run

# Preview documentation
make serve

Architekturübersicht

Zwei-Ordner-Design

┌─────────────────────┐     ┌─────────────────────────────┐
│   specs/original/   │────▶│   docs/specifications/api/  │
│   (READ-ONLY)       │     │   (GENERATED)               │
│   - Downloaded      │     │   - Domain specs            │
│   - Gitignored      │     │   - Master spec             │
│   - ETag cached     │     │   - GitHub Pages            │
└─────────────────────┘     └─────────────────────────────┘

Pipeline-Ablauf

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

Verzeichnisstruktur

Verzeichnis	Zweck	Git-Status
specs/original/	F5-Quellspezifikationen	Gitignored
specs/discovered/	API-Discovery-Ausgabe	Verfolgt (openapi.json, session.json)
docs/specifications/api/	Generierte Domain-Spezifikationen	Gitignored
scripts/	Python-Pipeline-Skripte	Verfolgt
config/	Pipeline-Konfiguration	Verfolgt
reports/	Generierte Berichte	Gitignored

Workflow-Muster

1. Discovery-Workflow

Voraussetzungen:

• VPN-Verbindung zur F5 XC-Umgebung
• Gültige API-Anmeldedaten

# 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

Discovery erfasst:

• Tatsächliche Pflicht-/optionale Felder
• Enum-Werte aus Live-Antworten
• Standardwerte
• Mustervalidierungen
• Antwortbeispiele

2. Release-Workflow

Releases werden automatisiert:

1. Täglicher Zeitplan (6:00 Uhr UTC) oder Push auf main löst den Workflow aus
2. ETag-Prüfung stellt fest, ob sich F5-Spezifikationen geändert haben
3. Pipeline verarbeitet und reichert Spezifikationen an
4. Version wird aus Git-Tags berechnet: git describe --tags --abbrev=0
5. Direkter Commit + Tag erstellt (kein Versions-Bump-PR)
6. GitHub Release mit Changelog erstellt
7. Dokumentation auf GitHub Pages bereitgestellt

Regeln für Versions-Bumps:

Bedingung	Bump-Typ	Beispiel
[major] im Commit	Major	1.0.0 → 2.0.0
BREAKING CHANGE im Commit	Major	1.0.0 → 2.0.0
Neue Domain-Spezifikation hinzugefügt	Minor	1.0.0 → 1.1.0
Jede andere Änderung	Patch	1.0.0 → 1.0.1

3. Entwicklungsworkflow

# 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

Discovery im Detail

Was ist Discovery?

Discovery erkundet die Live-F5 XC-API, um Folgendes zu finden:

• Undokumentierte Einschränkungen: Pflichtfelder, die in OpenAPI nicht als solche markiert sind
• Tatsächliche Enum-Werte: Echte in der Produktion verwendete Werte
• Standardverhalten: Vom Server angewendete Werte, wenn Felder weggelassen werden
• Antwortmuster: Tatsächliche Datenstrukturen

Discovery-Konfiguration

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

Discovery-Erweiterungen

Discovery fügt x-discovered-*-Erweiterungen zu Spezifikationen hinzu:

{
  "properties": {
    "name": {
      "type": "string",
      "x-discovered-required": true,
      "x-discovered-pattern": "^[a-z][a-z0-9-]*$",
      "x-discovered-examples": ["my-app", "prod-lb"]
    }
  }
}

Einschränkungsanalysebericht

reports/constraint-analysis.md

make constraint-report

Release-Prozess

Inhalt des Release-Pakets

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

Manuelles Auslösen des Workflows

gh workflow run sync-and-enrich.yml
gh run watch

Konfigurationshandbuch

Anreicherungskonfiguration

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

Normalisierungskonfiguration

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

Spectral-Linting-Regeln

config/spectral.yaml

extends:
  - spectral:oas

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

OpenAPI-Erweiterungen

Die Anreicherungspipeline verwendet Vendor-Erweiterungen, um Validierungs- und Standardwert-Metadaten einzubetten.

Erweiterungskategorien

Erweiterung	Bedeutung	Auswirkung
x-f5xc-server-default	Der F5 XC API-Server wendet diesen Wert an, wenn das Feld weggelassen wird	Das Feld ist optional; das Weglassen erzeugt das dokumentierte Standardverhalten
x-f5xc-recommended-value	Die F5 XC-Webkonsole befüllt diesen Wert für neue Ressourcen vor	Das Feld hat keinen Serverstandard, aber dieser Wert repräsentiert eine typische Konfiguration
x-f5xc-recommended-oneof-variant	Die F5 XC-Konsole wählt diese OneOf-Variante vor	Identifiziert die typische Auswahl, wenn mehrere sich gegenseitig ausschließende Optionen vorhanden sind
x-f5xc-conflicts-with	Listet andere Eigenschaften auf, die nicht zusammen mit diesem Feld verwendet werden können	Die Eigenschaft ist Teil einer OneOf-Gruppe; nur eine der in Konflikt stehenden Eigenschaften kann angegeben werden

Pflichtfeld-Erweiterungen

Erweiterung	Quelle	Zweck
x-ves-required: "true"	F5 XC-Originalspezifikation	Feld erfordert einen Nicht-Null-/Nicht-leer-Wert
x-f5xc-required-for	Anreicherungspipeline	Kontextspezifischer Pflichtstatus

x-f5xc-required-for-Kontexte:

• create: Erforderlich beim Erstellen der Ressource
• update: Erforderlich beim Aktualisieren der Ressource
• minimum_config: Erforderlich für die Mindestkonfiguration

Standardwert- und OneOf-Erweiterungen

Erweiterung	Zweck
x-f5xc-server-default: true	Markiert vom Server angewendete Standardwerte
x-f5xc-recommended-value	Vom F5 XC-Konsolenvorbefüllter Wert
x-f5xc-recommended-oneof-variant	Empfohlene OneOf-Variante
x-f5xc-conflicts-with	Gegenseitige Ausschlussmäßigkeit mit anderen OneOf-Eigenschaften

x-f5xc-server-default

Typ: boolean

Wenn true, gibt dies an, dass der begleitende default-Wert vom F5 XC API-Server durchgesetzt wird. Felder mit dieser Erweiterung können sicher aus API-Anfragen weggelassen werden — der Server wendet den Standardwert automatisch an.

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

x-f5xc-recommended-value

Typ: any (entspricht dem Feldtyp)

Gibt einen Wert an, den die F5 XC-Webkonsole als vorbefüllten Standardwert verwendet. Dieser Wert wird nicht vom Server durchgesetzt, repräsentiert aber die typische Ausgangskonfiguration für neue Ressourcen, die über die Konsole erstellt werden.

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

x-f5xc-recommended-oneof-variant

Typ: object (Zuordnung von Gruppenname zu Variantenname)

Für Schemas mit sich gegenseitig ausschließenden Feldgruppen wird angegeben, welche Variante die Standard- oder häufigste Wahl ist. Der Schlüssel ist der OneOf-Gruppenname und der Wert ist der empfohlene Variantenfeldname.

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

x-f5xc-conflicts-with

Typ: array aus Zeichenketten

Hinzugefügt: v3.2.0 (Issue #494)

Deklariert gegenseitige Ausschlussbeziehungen zwischen OneOf-Gruppenmitgliedern. Automatisch aus x-ves-oneof-field-*-Erweiterungen abgeleitet. Dies ermöglicht nachgelagerten Werkzeugen (Terraform, CLI, MCP), Konflikte auf Schema-Ebene statt zur Laufzeit zu validieren.

host_header:
  type: string
  x-f5xc-conflicts-with: ["use_origin_server_name"]

use_origin_server_name:
  type: object
  x-f5xc-conflicts-with: ["host_header"]

Anwendungsfälle:

• Terraform-Provider können Validierungsregeln generieren
• CLI-Werkzeuge können vor in Konflikt stehenden Feldkombinationen warnen
• KI-Assistenten können korrekte OneOf-Konfigurationen generieren
• IDE-Erweiterungen können konfliktbewusste Autovervollständigung bereitstellen

Quelle: Automatisch aus nativen F5 x-ves-oneof-field-*-Erweiterungen während der Pipeline-Anreicherung abgeleitet.

Auswirkungen von Validierungsregeln

Der Anreicherungsprozess untersucht x-ves-validation-rules, um den Pflichtstatus abzuleiten:

Regel	Auswirkung
ves.io.schema.rules.message.required: "true"	Feld ist Pflichtfeld
ves.io.schema.rules.uint32.gte: N	Wenn N >= 1 und kein Serverstandard, ist das Feld Pflichtfeld
ves.io.schema.rules.repeated.min_items: N	Wenn N >= 1, erfordert das Array mindestens N Elemente
ves.io.schema.rules.string.min_bytes: N	Wenn N >= 1, erfordert die Zeichenkette mindestens N Bytes

Ressourcen mit vom Server angewendeten Standardwerten

Einige Ressourcen akzeptieren leere Spezifikationen, weil der Server Standardwerte anwendet:

Ressource	Vom Server angewendete Standardwerte
app_firewall	monitoring: \{\}, default_detection_settings: \{\}
rate_limiter	limits: [], user_identification: []
api_definition	swagger_specs: [], Standard-api_groups
healthcheck	jitter: 0, jitter_percent: 0, verschachtelte http_health_check-Standardwerte

Für diese Ressourcen kann x-f5xc-required-for.create false sein, auch wenn x-ves-required true ist.

Standardwertmuster

Muster	Typ	Beispiel
\{\}	Leeres Objekt (Auswahlauswahl)	monitoring: \{\}
[]	Leeres Array	expected_status_codes: []
0	Numerisch	jitter: 0
""	Zeichenkette	expected_response: ""
false	Boolesch	use_http2: false

Entdeckte Standardwerte hinzufügen

1. Ressource in F5 XC mit minimaler Spezifikation über die API erstellen
2. Ressource zurücklesen, um vom Server angewendete Werte zu sehen
3. Standardwerte in config/discovered_defaults.yaml dokumentieren
4. Pipeline ausführen: make pipeline
5. Überprüfen mit: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

Fehlerbehebung

Pre-commit dauert zu lange

Die Pipeline wird bei jedem Commit ausgeführt, um Konsistenz sicherzustellen. Für Work-in-Progress-Commits:

git commit --no-verify -m "WIP: work in progress"
# Run before final commit: make pre-commit-run

Discovery schlägt fehl

# 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

Lint-Fehler in generierten Spezifikationen

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

Beheben Sie Probleme in der Anreicherungs-/Normalisierungskonfiguration, nicht in den Ausgabedateien.

Versionssystem

Die Version wird aus Git-Tags abgeleitet (z. B. v2.0.38), wodurch Race Conditions vermieden werden, die bei gleichzeitigen PRs zu Merge-Konflikten führten.

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

Fehlende Spezifikationen nach dem Klonen

Generierte Spezifikationen sind gitignored:

make build  # Downloads and generates everything

Große Datei blockiert

Ausnahme zu .pre-commit-config.yaml hinzufügen:

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

Kurzreferenz

Make-Ziele

Ziel	Beschreibung
make build	Vollständiger Build (Herunterladen + Pipeline)
make rebuild	Schneller Rebuild (Download überspringen)
make download	Spezifikationen herunterladen (ETag gecacht)
make download-force	Download erzwingen
make pipeline	Anreicherungspipeline ausführen
make lint	Spectral-Linting
make serve	Lokaler Dokumentationsserver
make discover	API-Discovery (VPN erforderlich)
make push-discovery	Discovery-Daten committen
make clean	Generierte Dateien entfernen
make pre-commit-run	Alle Qualitätsprüfungen ausführen

Umgebungsvariablen

Variable	Zweck
F5XC_API_URL	F5 XC-Mandanten-API-URL
F5XC_API_TOKEN	API-Authentifizierungstoken

Wichtige Dateien

Datei	Zweck
.etag	Zuletzt heruntergeladener ETag
CHANGELOG.md	Automatisch generierter Changelog
config/enrichment.yaml	Anreicherungsregeln
config/normalization.yaml	Normalisierungsregeln
config/discovery.yaml	Discovery-Einstellungen
config/spectral.yaml	Linting-Regeln
scripts/utils/version_calculator.py	Tag-basierte Versionsberechnung

Hinweis: Die Version wird aus Git-Tags abgeleitet (z. B. v2.0.38), nicht aus einer .version-Datei.