OpenAPI Linting mit Spectral – Eine einfachere Methode

Zwei Ingenieure desselben Teams liefern in derselben Woche zwei Endpunkte aus. Einer gibt created_at zurück, der andere createdAt. Einer paginiert mit ?page=, der andere mit ?offset=. Für sich genommen ist nichts davon falsch. Zusammen lassen sie Ihre API jedoch so wirken, als wäre sie von Fremden zusammengesetzt worden, und jeder Client, der sie konsumiert, zahlt den Preis. Die OpenAPI-Datei ist gültig. Sie wird geparst, in Swagger UI gerendert, ein SDK wird generiert. Sie ist einfach inkonsistent, und ein einfacher Validator hat dazu nichts zu sagen.

Genau diese Lücke füllt ein Linter. Ein Validator beantwortet die Frage „Ist diese Spezifikation ein gültiges OpenAPI?“. Ein Linter beantwortet die Frage „Folgt diese Spezifikation den Regeln, auf die wir uns geeinigt haben?“. Das beliebteste Open-Source-Tool für die zweite Frage ist Spectral, Stoplights Linter für JSON- und YAML-Dokumente. Es wird mit einem integrierten OpenAPI-Regelwerk geliefert, ermöglicht es Ihnen, eigene Regeln zu schreiben, und läuft über das Terminal oder Ihren Editor. Wenn Sie eine kostenlose, skriptfähige Möglichkeit suchen, einen API-Styleguide durchzusetzen, ist Spectral die offensichtliche erste Anlaufstelle, und dieser Leitfaden zeigt Ihnen, wie Sie es richtig verwenden.

Es zeigt Ihnen auch den Kompromiss. Spectral ist ein Regelwerk, das Sie zusammenstellen und pflegen. Für Teams, die Konsistenzprüfungen, Mock-Server und ausführbare Tests lieber aus einer Hand erhalten möchten, ohne YAML-Regeln manuell schreiben zu müssen, integriert Apidog diese Arbeit direkt in die Designoberfläche. Wir werden Spectral zuerst vollständig würdigen und dann zeigen, wo der All-in-One-Ansatz Ihnen den Wartungsaufwand erspart.

Was Spectral tatsächlich tut

Spectral ist ein generischer Linter. Sie weisen ihn auf ein strukturiertes Dokument, geben ihm einen Satz von Regeln, und er meldet jede Stelle, an der das Dokument eine Regel verletzt, mit Zeilennummer und Schweregrad. Es ist nicht spezifisch für OpenAPI; es versteht OpenAPI, AsyncAPI und Arazzo sofort, und Sie können jede JSON- oder YAML-Datei mit benutzerdefinierten Regeln linten.

Der Grund, warum es für die API-Arbeit wichtig ist, ist das integrierte spectral:oas-Regelwerk. Dieses Regelwerk kodiert eine lange Liste von OpenAPI-Konventionen: Operationen sollten eine operationId haben, das info-Objekt sollte eine Beschreibung und einen Kontakt enthalten, Tags sollten vor ihrer Verwendung definiert werden, Parameter sollten sich nicht duplizieren. Führen Sie es gegen eine reale Spezifikation aus und Sie erhalten fast immer beim ersten Versuch eine Liste von Warnungen. Keine davon unterbricht einen Parser. Alle machen die Spezifikation schwieriger zu handhaben.

Dies ist eine andere Aufgabe als die strukturelle Validierung. Ein Tool wie swagger-cli oder Redocly beantwortet die Frage, ob das Dokument dem OpenAPI-Schema entspricht. Spectral beantwortet zusätzlich die Frage, ob das Dokument Ihrem Hausstil folgt. Sie möchten beides, und die beiden Prüfungen lassen sich sauber in einer Pipeline kombinieren. Den Validierungsteil behandeln wir im Leitfaden zum Validieren von OpenAPI-Spezifikationen; dieser Artikel befasst sich mit dem Stil- und Konsistenzteil.

Spectral installieren und Ihren ersten Lint ausführen

Spectral wird als npm-Paket ausgeliefert. Das CLI ist @stoplight/spectral-cli. Installieren Sie es global:

npm install -g @stoplight/spectral-cli

Node.js ist die einzige Systemabhängigkeit, daher kann jede Maschine oder jedes CI-Image mit bereits installiertem Node es ausführen. Wenn Sie es lieber nicht global installieren möchten, funktioniert npx @stoplight/spectral-cli ... auf temporären Build-Runnern.

Spectral benötigt ein Regelwerk, um zu wissen, was überprüft werden soll. Die Konvention ist eine Datei namens .spectral.yaml in Ihrem Arbeitsverzeichnis. Die kleinste nützliche erweitert die integrierten OpenAPI-Regeln:

# .spectral.yaml
extends: ["spectral:oas"]

Linten Sie nun eine Spezifikation. Mit einer .spectral.yaml im aktuellen Verzeichnis nimmt Spectral sie automatisch auf:

spectral lint openapi.yaml

Oder verweisen Sie explizit auf ein Regelwerk:

spectral lint openapi.yaml --ruleset .spectral.yaml

Die Ausgabe ist absichtlich lesbar. Jedes Ergebnis zeigt die Zeile und Spalte, den Schweregrad, die ausgelöste Regel und eine menschenlesbare Nachricht:

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

Dieser erste Durchlauf gegen eine bestehende Spezifikation ist der Moment, in dem die meisten Teams erkennen, wie viel Abweichung sich eingeschlichen hat. Die Regeln wurden nie durchgesetzt, also hat niemand sie befolgt.

Eigene Regeln schreiben

Das integrierte Regelwerk ist ein Ausgangspunkt, nicht das Ziel. Der wahre Wert von Spectral liegt darin, die Konventionen Ihres Teams als Regeln zu kodieren, die eine Maschine bei jeder Änderung überprüft. Eine Regel besteht aus vier beweglichen Teilen: was zu überprüfen ist (given, ein JSONPath-Ausdruck), was geprüft werden soll (then, eine Funktion), wie laut der Bericht sein soll (severity) und was zu sagen ist, wenn es fehlschlägt (message).

Hier ist eine Regel, die Kebab-Case-Pfade durchsetzt, eine gängige Hauskonvention:

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

Das given wählt jeden Pfadschlüssel aus. Das then führt die integrierte pattern-Funktion gegen einen regulären Ausdruck aus. Alles, was dem Muster nicht entspricht, wird als Warnung mit Ihrer Nachricht gemeldet. Sie können Integer-IDs zugunsten von UUIDs verbieten, eine Fehlerantwort bei jedem POST fordern, Versionsnummern in Server-URLs untersagen oder verlangen, dass jede Operation eine Beschreibung enthält. Spectral liefert mehrere Kernfunktionen (truthy, pattern, schema, length, enumeration und mehr), sodass die meisten Konventionen überhaupt keinen Code benötigen.

Wenn eine Regel Logik benötigt, die eine Funktionsoption nicht ausdrücken kann, ermöglicht Spectral das Schreiben von Regeln in JavaScript oder TypeScript und den Import benutzerdefinierter Funktionen. Hier wird das Tool leistungsfähig und hier beginnt der Wartungsaufwand. Wenn Sie so tief gehen möchten, haben wir eine vollständige Anleitung zum Erstellen benutzerdefinierter Spectral-Regeln mit TypeScript.

Schweregrad und das Fehlschlagen des Builds

Jede Spectral-Regel hat einen Schweregrad: error, warn, info oder hint. Standardmäßig beendet die CLI die Ausführung nur mit einem Nicht-Null-Code, wenn sie einen error findet. Warnungen werden ausgegeben, aber die Ausführung schlägt nicht fehl. Das ist in Ordnung, während Sie eine veraltete Spezifikation bereinigen und nicht möchten, dass tausend Warnungen jede Zusammenführung blockieren.

Sobald Ihre Spezifikation sauber ist, ziehen Sie die Daumenschrauben an. Das Flag --fail-severity steuert den Schwellenwert:

spectral lint openapi.yaml --fail-severity=warn

Jetzt gibt eine Warnung auch den Exit-Code 1 zurück, den ein CI-Schritt liest, um sich selbst als fehlgeschlagen zu markieren. Dies ist der Mechanismus, der einen Linter in ein echtes Qualitätstor verwandelt: Die Pipeline blockiert die Zusammenführung in dem Moment, in dem die Spezifikation vom Styleguide abweicht. Sie können auch einzelne Regel-Schweregrade in Ihrem Regelwerk überschreiben, indem Sie eine Regel, die Ihnen wichtig ist, von warn auf error hochstufen oder eine, die nicht zu Ihrem Team passt, stummschalten, indem Sie sie auf off setzen.

Spectral in CI ausführen

Ein Linter, der nur läuft, wenn sich jemand daran erinnert, ist kein Tor. Der Sinn ist, ihn bei jedem Push, auf einer sauberen Maschine, mit demselben Regelwerk für alle auszuführen. Spectral macht dies kurz. Hier ist ein GitHub Actions Job, der die Spezifikation bei jedem Pull Request, der sie berührt, lintet:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

Für eine umfassendere Berichterstattung kann Spectral JUnit XML ausgeben, das die meisten CI-Dashboards in einen Pass/Fail-Baum zerlegen:

spectral lint openapi.yaml -f junit -o results.xml

Verbinden Sie dieses Artefakt mit Ihrem Dashboard und jeder Mitwirkende sieht, welche Regel wo fehlgeschlagen ist, ohne Rohprotokolle lesen zu müssen. Wenn Sie das umfassendere Bild der Schichtung von Strukturprüfungen, Linting und Erkennung von Breaking Changes zusammen sehen möchten, gehen die OpenAPI-in-CI-Muster über jedes einzelne Tool hinaus. Die Behandlung der Spezifikation als Code ist die Denkweise, die all dies zum Erfolg führt.

Wo Spectral viel von Ihnen verlangt

Spectral ist gut in dem, was es tut. Der ehrliche Haken ist, dass es eine Sache tut, und der Rest des Spezifikationslebenszyklus ist Ihr Problem, das Sie zusammenfügen müssen. Ein paar Realitäten zeigen sich, sobald ein Team es über die Demo hinaus annimmt.

Sie besitzen das Regelwerk. Die integrierten spectral:oas-Regeln sind generisch. Ihr eigentlicher Styleguide lebt in benutzerdefinierten Regeln, die Sie schreiben, überprüfen, versionieren und aktuell halten, während sich Konventionen entwickeln. Dieses Regelwerk wird zu einer kleinen Codebasis mit eigenem Wartungsaufwand, und JSONPath plus benutzerdefinierte Funktionen ist eine Fähigkeit, die nicht jeder im Team besitzt.

Es lintet das Dokument, nicht die API. Spectral liest die Datei. Es kann Ihnen nicht sagen, ob der laufende Dienst tatsächlich das zurückgibt, was die Spezifikation verspricht. Eine Spezifikation kann jede Lint-Regel bestehen und dennoch einen Endpunkt beschreiben, von dem die Implementierung bereits vor Monaten abgewichen ist. Diese Lücke zu schließen bedeutet, echte Anfragen zu senden und Antworten zu überprüfen, was ein völlig anderes Tool ist.

Es ist ein Teil einer längeren Kette. Nach dem Linting benötigen Sie immer noch Mocks für Frontend-Teams, eine Dokumentationsseite und eine automatisierte Testsuite. Jedes ist ein separates Tool, das installiert, konfiguriert und mit der Spezifikation synchron gehalten werden muss. Der Linter weiß nichts davon, sodass die Spezifikation in jeder Phase erneut geparst und neu interpretiert wird.

Nichts davon ist ein Kritikpunkt an Spectral. Es ist ein fokussierter Linter und ehrlich in seinem Umfang. Aber „fokussiert“ bedeutet, dass die Integrationsarbeit bei Ihnen liegt.

Der einfachere Weg: Konsistenz direkt in die Designoberfläche integriert

Hier ist der andere Weg. Anstatt Konsistenz als einen Lint-Schritt zu behandeln, der nach dem Schreiben der Spezifikation angehängt wird, behandelt Apidog sie als Teil des Schreibens der Spezifikation.

Apidog ist eine All-in-One-API-Plattform: Sie entwerfen das Schema, debuggen Anfragen, erstellen Testszenarien, mocken Endpunkte und veröffentlichen Dokumente in einem Arbeitsbereich. Da das Design innerhalb des Tools stattfindet, erfolgen die Konsistenzprüfungen während des Tippens. Der visuelle Designer zeigt strukturelle Probleme sofort an, sobald sie auftreten, ähnlich wie ein Compiler einen Syntaxfehler unterstreicht, sodass Sie sie beheben, bevor sie jemals einen Commit erreichen. Sie führen danach keinen separaten Linter aus; der Editor ist der Linter.

Der größere Unterschied liegt in allem, was nachgelagert ist. Derselbe Vertrag, den Sie entwerfen, wird zu Ihrem Mock-Server, Ihren interaktiven Dokumenten und Ihren Testszenarien, ohne erneutes Parsen und ohne zweites Tool zur Synchronisierung. Wenn Sie diese Prüfungen in einer Pipeline wünschen, führt die Apidog CLI Ihre Testszenarien unbeaufsichtigt vom Terminal aus aus und beendet die Ausführung bei Fehler mit einem Nicht-Null-Code, genau das Gate-Verhalten, das Sie von einem Linter wollten, außer dass es die laufende API gegen den Vertrag testet, anstatt nur die Datei zu lesen. Installieren Sie es mit einem npm-Befehl und weisen Sie es auf ein Szenario:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

Das füllt die Lücke, die Spectral offen lässt. Spectral bestätigt, dass das Dokument Ihrem Stil folgt. Die Apidog CLI bestätigt, dass die Implementierung immer noch dem Dokument entspricht. Für die vollständige Flag-Referenz führen Sie apidog run --help aus oder lesen Sie den vollständigen CLI-Leitfaden.

Der Kompromiss ist also real und sollte klar genannt werden. Spectral bietet Ihnen einen kostenlosen, skriptfähigen, herstellerneutralen Linter, den Sie selbst zusammenstellen und warten. Apidog bietet Ihnen Konsistenz, Mocking, Dokumente und ausführbare Tests aus einer einzigen Quelle der Wahrheit, mit viel weniger Aufwand für die Verkabelung. Wenn ein portabler Lint-Schritt in einer bestehenden Toolchain alles ist, was Sie brauchen, ist Spectral eine gute Antwort. Wenn Sie den gesamten Lebenszyklus ohne ein eigenes Tooling-Projekt aufrechterhalten möchten, kostet Sie der integrierte Weg auf lange Sicht weniger.

Spectral vs. Apidog auf einen Blick

Nutzen Sie die Tabelle als Entscheidungshilfe, nicht als Anzeigetafel. Die richtige Wahl ist diejenige, die dazu passt, wie viel vom Lebenszyklus Sie einem Tool überlassen möchten.

Häufig gestellte Fragen

Ist Spectral kostenlos? Ja. Spectral ist Open Source unter der Apache 2.0-Lizenz, gepflegt von Stoplight. Die CLI, das integrierte OpenAPI-Regelwerk und die Erstellung benutzerdefinierter Regeln sind alle kostenlos nutzbar.

Validiert Spectral, ob meine Spezifikation ein gültiges OpenAPI ist? Teilweise. Die integrierten Regeln fangen viele strukturelle Probleme ab, aber Spectral ist ein Linter, kein dedizierter Schema-Validator. Kombinieren Sie es mit einem Validator für eine vollständige strukturelle Abdeckung. Der Leitfaden zum Validieren von OpenAPI-Spezifikationen behandelt diese Seite, und die besten OpenAPI-Validator-Tools vergleichen die Optionen.

Kann Spectral meine laufende API testen? Nein. Spectral liest nur die Spezifikationsdatei. Um zu überprüfen, ob die Live-API dem Vertrag entspricht, benötigen Sie einen Runner, der echte Anfragen sendet und Antworten überprüft, wie die Apidog CLI.

Wie kann ich erreichen, dass eine Spectral-Warnung meinen CI-Build fehlschlagen lässt? Führen Sie spectral lint openapi.yaml --fail-severity=warn aus. Standardmäßig lässt nur der Schweregrad error den Build fehlschlagen; --fail-severity=warn bewirkt, dass Warnungen ebenfalls einen Nicht-Null-Exit-Code zurückgeben.

Was ist der Unterschied zwischen Spectral und Apidog? Spectral ist ein fokussierter Open-Source-Linter, den Sie konfigurieren und pflegen. Apidog ist eine All-in-One-Plattform, auf der Design, Konsistenzprüfungen, Mocking, Dokumentation und Tests zusammenleben, sodass Sie weniger zusammenfügen und weniger synchron halten müssen. Siehe Apidog vs. Swagger für einen verwandten Vergleich der Design-Tool-Landschaft.

Zusammenfassung

Spectral löst ein echtes Problem, das einfache Validatoren ignorieren: Eine OpenAPI-Spezifikation konsistent mit den Konventionen zu halten, auf die sich Ihr Team geeinigt hat. Installieren Sie @stoplight/spectral-cli, erweitern Sie spectral:oas, fügen Sie ein paar benutzerdefinierte Regeln hinzu und sichern Sie Ihre Pipeline mit --fail-severity=warn. Für viele Teams ist das ausreichend, und es kostet nichts.

Die Kosten zeigen sich später, in den Regeln, die Sie pflegen, und dem Rest des Lebenszyklus, den Sie um den Linter herum aufbauen. Wenn Sie Konsistenz, Mocks, Dokumente und ausführbare Tests lieber aus einer einzigen Quelle der Wahrheit erhalten möchten, laden Sie Apidog herunter und erstellen Sie Ihre Spezifikation dort, wo die Prüfungen bereits Teil der Oberfläche sind. So oder so ist das Ziel dasselbe: eine Spezifikation, der Ihr gesamtes Team vertrauen kann, durchgesetzt von einer Maschine statt einer Hoffnung.