Auf Upstream-Spezifikationen angewendete Korrekturen

Der Reconciler (scripts/reconcile.py) wendet vier Kategorien von Korrekturen auf Upstream-Spezifikationen an. Constraint-Korrekturen ändern API-Verträge, um dem beobachteten Verhalten zu entsprechen. Alle anderen Korrekturen betreffen ausschließlich Metadaten und verändern keine API-Verträge.

Constraint-Korrekturen

Diese Korrekturen passen OpenAPI-Schema-Constraints an, damit die Spezifikation dem entspricht, was die Live-API tatsächlich durchsetzt. Jede Korrektur wird durch ein Discrepancy-Objekt gesteuert, das während der Validierung erzeugt wird.

Strategie	Auslöser	Funktionsweise	Vertragsänderung
Relax	SPEC_STRICTER	Spezifikation lehnt Werte ab, die die API akzeptiert. Senkt minLength/minimum, erhöht maxLength/maximum, fügt fehlende Enum-Werte hinzu.	Ja — erweitert akzeptierte Werte
Tighten	SPEC_LOOSER	Spezifikation akzeptiert Werte, die die API ablehnt. Erhöht minLength/minimum, senkt maxLength/maximum, beschränkt Enums auf beobachtete Werte.	Ja — schränkt akzeptierte Werte ein
Add	MISSING_CONSTRAINT	API erzwingt einen Constraint, der in der Spezifikation nicht dokumentiert ist. Fügt den Constraint dem Schema hinzu.	Ja — fügt neuen Constraint hinzu
Remove	EXTRA_CONSTRAINT	Spezifikation deklariert einen Constraint, den die API ignoriert. Entfernt den Constraint aus dem Schema.	Ja — entfernt Constraint

Achtung

Constraint-Korrekturen ändern den API-Vertrag. Sie werden nur angewendet, wenn sie durch Evidenz aus Schemathesis oder Constraint-Validierungstests gegen die Live-API gestützt werden.

Unterstützte Constraint-Typen

Die 10 OpenAPI-Constraint-Kategorien, die getestet und korrigiert werden:

• String-Länge — minLength, maxLength
• Muster — pattern (Regex)
• Numerische Grenzen — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• Pflichtfelder — required
• Enum-Werte — enum
• Array-Grenzen — minItems, maxItems, uniqueItems
• Objektstruktur — additionalProperties, properties, propertyNames
• Komposition — oneOf, anyOf, allOf
• Abhängigkeiten — dependentRequired, dependentSchemas
• Datentypen — type, format

Spectral-Anreicherungen

Diese Korrekturen beheben OAS3-Qualitätsprobleme, die durch Spectral-Linting gefunden wurden. Sie fügen Metadaten hinzu oder korrigieren diese, ohne das API-Verhalten zu ändern.

Server-Block-Injektion

Regel: oas3-api-servers | Vertragsänderung: Nein

Fügt das F5 XC Tenant-URL-Template zu Spezifikationen hinzu, denen ein servers-Block fehlt:

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

Die Server-URL und Variablenwerte stammen aus spectral.servers in validation.yaml.

Kontaktinformationen-Injektion

Regel: info-contact | Vertragsänderung: Nein

Fügt Kontaktinformationen zu info.contact für Spezifikationen hinzu, denen diese fehlen:

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

Die Werte stammen aus spectral.contact in validation.yaml.

Operations-Tag-Ableitung

Regel: operation-tags | Vertragsänderung: Nein

Leitet einen Tag aus dem URL-Pfad-Präfix für nicht getaggte Operationen ab. Für einen Pfad wie /api/config/namespaces/{namespace}/healthchecks lautet der Tag config (das zweite Nicht-Parameter-Segment). Der Tag wird sowohl dem tags-Array der Operation als auch der tags-Liste auf Spezifikationsebene hinzugefügt.

Entfernung ungenutzter Komponenten

Regel: oas3-unused-component | Vertragsänderung: Nein

Entfernt Komponentenschemata aus components.schemas, die nirgendwo in der Spezifikation referenziert werden. Reduziert die Spezifikationsgröße, ohne eine Operation zu beeinflussen.

OperationId-Deduplizierung

Regel: operation-operationId-unique | Vertragsänderung: Nein

Hängt die HTTP-Methode als Suffix an (z. B. ListItems_get), wenn mehrere Operationen dieselbe operationId teilen. Dadurch wird jede operationId für Code-Generatoren eindeutig.

Entfernung ungültiger Example-/Default-Werte

Regel: oas3-valid-schema-example | Vertragsänderung: Nein

Entfernt example- oder default-Werte aus Schemata, wenn der Wert nicht den eigenen Constraints des Schemas entspricht (falscher Typ, außerhalb des Bereichs usw.). Verhindert, dass Code-Generatoren ungültige Beispiel-Payloads erzeugen.

Script-Tag-Entfernung

Regel: no-script-tags-in-markdown | Vertragsänderung: Nein

Entfernt <script>-Tags aus description-Feldern mittels Regex-Ersetzung. Einige Upstream-Spezifikationen enthalten eingefügte Script-Tags, die Dokumentations-Renderer beschädigen.

Sicherheitsmetadaten

Vertragsänderung: Nein (nur Dokumentation)

Jede Spezifikation erhält ein apiKeyAuth-Sicherheitsschema, sofern nicht bereits eines vorhanden ist. Dies wird immer injiziert, unabhängig davon, ob Spectral es beanstandet hat.

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

Die Schema-Definition stammt aus spectral.security_scheme in validation.yaml. Dies informiert API-Konsumenten über die Authentifizierung, ändert jedoch nicht das Laufzeitverhalten.

JSON-Formatierung

Vertragsänderung: Nein

Alle ausgegebenen JSON-Spezifikationen durchlaufen einen Biome-kompatiblen Array-Komprimator (_compact_short_arrays in scripts/utils/spec_loader.py). Kurze Arrays, die innerhalb von 120 Zeichen passen, werden auf eine einzelne Zeile zusammengefasst:

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

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

Arrays, die den Zeilenlängen-Schwellenwert überschreiten, bleiben mehrzeilig.

Korrektur-Priorität

Wenn mehrere Korrekturstrategien anwendbar sein könnten, verwendet der Reconciler eine in reconciliation.priority konfigurierte Prioritätsreihenfolge:

1. existing — Verwendet den bestehenden Spezifikations-Constraint, wenn er gültig ist
2. discovery — Verwendet das entdeckte Live-API-Verhalten
3. inferred — Leitet aus Mustern über ähnliche Endpunkte hinweg ab

Jede korrigierte Spezifikation wird nach Anwendung aller Korrekturen mit openapi-spec-validator validiert. Wenn die Validierung fehlschlägt, wird die ursprüngliche Spezifikation als Fallback verwendet und die Korrektur als Fehler protokolliert.