Spectral Linting-Regeln

Das Projekt verwendet Spectral für OAS3-Linting mit einer Zwei-Konfigurationen-Architektur, die CI/externes Tooling von der benutzerdefinierten Logik der Pipeline trennt.

Zwei-Konfigurationen-Architektur

`.spectral.yaml` — Basiskonfiguration

Wird vom GitHub Super-Linter und allen externen CI-Tools verwendet. Erweitert spectral:oas (das integrierte OAS-Regelwerk). Enthält keine benutzerdefinierten Funktionen — dadurch bleibt die Kompatibilität mit Tools gewährleistet, die Spectral ohne Zugriff auf das Verzeichnis spectral/functions/ ausführen.

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` — Pipeline-Konfiguration

Wird von scripts/spectral_lint.py (sowohl im Discover- als auch im Gate-Modus) verwendet. Erweitert die Basiskonfiguration und fügt die benutzerdefinierte Funktion f5-path-params hinzu:

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

Warum `path-params` deaktiviert ist

Die integrierte path-params-Regel von Spectral kennzeichnet fälschlicherweise F5 XC APIs, die Parameternamen mit Punktnotation wie {metadata.namespace} und {metadata.name} verwenden. Die integrierte Regel kann Punkte in Parameternamen nicht korrekt verarbeiten und meldet sie daher als nicht deklariert.

Die benutzerdefinierte Funktion f5-path-params (spectral/functions/f5-path-params.js) behandelt Punktnotation korrekt, indem sie den vollständigen {Platzhalter}-Inhalt mit den deklarierten Parameternamen abgleicht. Sie prüft sowohl Parameter auf Pfadebene als auch auf Operationsebene und meldet Fehler in beide Richtungen:

Ein Platzhalter im URL-Pfad, für den keine passende Parameterdeklaration existiert
Ein deklarierter Pfadparameter, der nicht im URL-Pfad vorkommt

Regelreferenz

Automatisch korrigierbare Regeln

Diese Regeln werden vom Reconciler automatisch korrigiert, wenn Verstöße erkannt werden. Siehe Angewandte Korrekturen für Details zu jeder Korrektur.

Regel	Schweregrad	Korrekturmethode	Beschreibung
`oas3-api-servers`	warn	`_add_servers`	Spezifikation muss einen `servers`-Block enthalten
`info-contact`	warn	`_add_contact`	`info` muss `contact` enthalten
`operation-tags`	warn	`_add_tags`	Jede Operation muss mindestens einen Tag besitzen
`oas3-unused-component`	warn	`_remove_unused_component`	Keine unreferenzierten Komponentenschemas
`operation-operationId-unique`	error	`_deduplicate_operation_id`	Alle operationIds müssen eindeutig sein
`oas3-valid-schema-example`	error	`_fix_schema_example`	Beispiele/Standardwerte müssen ihrem Schema entsprechen
`no-script-tags-in-markdown`	warn	`_strip_script_tags`	Keine `<script>`-Tags in Beschreibungen
`f5-path-params`	error	—	Pfadparameter müssen deklariert und verwendet werden

Nicht korrigierbare Regeln

Diese Regeln werden auf den Schweregrad info herabgestuft, da sie nicht sinnvoll automatisch korrigiert werden können:

Regel	Schweregrad	Beschreibung
`operation-description`	info	Operationen sollten eine Beschreibung haben
`info-description`	info	API-Info sollte eine Beschreibung haben

Pipeline-Integration

Der Spectral-Adapter (scripts/spectral_lint.py) wird in zwei Modi ausgeführt:

Discover-Modus (Vor-Reconcile)

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

Scannt specs/original/ und schreibt reports/spectral_report.json. Der Reconciler nutzt diesen Bericht zusammen mit dem Validierungsbericht.

Gate-Modus (Nach-Reconcile)

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

Scannt release/specs/ und schreibt reports/spectral_gate_report.json. Gibt Exit-Code 1 zurück, wenn Verstöße die konfigurierten Schwellenwerte überschreiten.

Verstoßzuordnung

Spectral-Verstöße werden in Discrepancy-Objekte mit drei Untertypen konvertiert:

Spectral-Regelkategorie	DiscrepancyType	Beispielregeln
Fehlendes erforderliches Element	`SPECTRAL_MISSING`	`oas3-api-servers`, `info-contact`, `operation-tags`
Ungültiges vorhandenes Element	`SPECTRAL_INVALID`	`oas3-valid-schema-example`, `no-script-tags-in-markdown`
Toter Code	`SPECTRAL_UNUSED`	`oas3-unused-component`