Zwei Ingenieure desselben Teams liefern in derselben Woche zwei Endpunkte aus. Der eine gibt created_at zurück, der andere createdAt. Der eine paginiert mit ?page=2, der andere mit ?offset=20. Der eine platziert Fehler in einem übergeordneten error-Objekt, der andere bettet eine message-Zeichenkette direkt ein. Beide bestehen die Code-Überprüfung, da die Prüfer die Logik und nicht die Benennung lesen. Sechs Monate später liest sich Ihre API-Oberfläche, als wäre sie von fünf verschiedenen Unternehmen geschrieben worden, und jede Client-Integration benötigt einen Sonderfall.
Ein OpenAPI-Linter existiert, um solche Abweichungen zu erkennen, bevor sie ausgeliefert werden. Er liest Ihr OpenAPI-Dokument, führt es gegen eine Reihe von Regeln aus (Operationen benötigen Beschreibungen, Schemata benötigen Beispiele, Eigenschaftsnamen folgen einer Namenskonvention, jede Antwort deklariert einen Medientyp) und lässt den Build fehlschlagen, wenn eine Regel verletzt wird. Es ist dieselbe Idee wie ESLint für JavaScript oder RuboCop für Ruby, nur auf Ihren API-Vertrag statt auf Ihren Anwendungscode gerichtet. Wenn Sie sich jemals gewünscht haben, dass die API-Design-Überprüfung so automatisiert werden könnte wie die Code-Formatierung, dann ist das genau das, was ein Linter tut.
Was ein OpenAPI-Linter tatsächlich prüft
Ein Linter arbeitet mit der Spezifikationsdatei, nicht mit einem laufenden Server. Richten Sie ihn auf openapi.yaml und er durchläuft jeden Pfad, jede Operation, jeden Parameter, jedes Schema und jede Antwort und wendet die Regeln nacheinander an. Regeln lassen sich in verschiedene Kategorien einteilen.
Gültigkeit. Ist dies überhaupt ein gültiges OpenAPI-Dokument? Werden alle $ref aufgelöst? Sind erforderliche Schlüsselwörter vorhanden? Dies überschneidet sich mit der einfachen Schema-Validierung, und die meisten Linter tun dies als Grundlage vor allem anderen.
Vollständigkeit. Hat jede Operation eine operationId, eine Zusammenfassung und eine Beschreibung? Erklärt sich jeder Parameter selbst? Enthält jedes Schema ein example? Dies sind die Regeln, die generierte Dokumentationen und SDKs tatsächlich nutzbar machen, und sie sind es, die Menschen am häufigsten vergessen.
Konsistenz. Das ist der wahre Gewinn. Eigenschaftsnamen verwenden eine einzige Namenskonvention. Pfadsegmente sind Plural-Substantive. Fehlerantworten teilen eine gemeinsame Form. Jede 2xx-Antwort deklariert application/json. Statuscodes werden so verwendet, wie es die HTTP-Spezifikation vorsieht. Keiner dieser Punkte ist isoliert betrachtet ein Fehler; zusammen machen sie den Unterschied zwischen einer API, die sich designt anfühlt, und einer, die sich zusammengestückelt anfühlt.
Hausstil. Ihre eigenen Konventionen. Vielleicht muss jeder Endpunkt getaggt sein. Vielleicht muss DELETE 204 zurückgeben. Vielleicht müssen interne Felder mit einem Präfix versehen sein. Das sind die Regeln, die niemand sonst hat, und die Fähigkeit, sie zu schreiben, unterscheidet einen Linter, mit dem Sie leben können, von einem, mit dem Sie kämpfen.
Eine Regel hat eine Schweregrad: Fehler, Warnung, Info oder Hinweis. Fehler lassen den Build fehlschlagen; Warnungen werden angezeigt, aber der Build wird zugelassen. Diese Schweregrad-Einstellung ermöglicht es Ihnen, Linting für eine bestehende API einzuführen, ohne am ersten Tag in 4.000 Verstößen zu ertrinken. Beginnen Sie alles als Warnung, beheben Sie die schlimmsten, und stufen Sie dann Regeln schrittweise zu Fehlern hoch. Für die konzeptionelle Seite, warum diese Regeln wichtig sind und wie Teams sie im großen Maßstab durchsetzen, finden Sie weitere Hintergrundinformationen unter wie Top-Unternehmen API-Design-Konsistenz gewährleisten.
Die wichtigsten OpenAPI-Linter-Optionen
Hier sind die Tools, die es wert sind, bekannt zu sein, mit einer ehrlichen Einschätzung, wo jedes einzelne passt.
Spectral
Spectral, von Stoplight, ist der De-facto-Standard. Es ist ein Open-Source-CLI und eine Bibliothek, die OpenAPI 2.0 und 3.x (sowie AsyncAPI und jedes JSON oder YAML über JSONPath) linted. Es wird mit einem integrierten spectral:oas-Regelwerk geliefert, das die gängigen Regeln abdeckt, und seine wahre Stärke sind benutzerdefinierte Regeln: Sie beschreiben, was geprüft werden soll, mithilfe von JSONPath-ähnlichen given-Selektoren plus einer then-Funktion, alles in einer YAML-Datei. Es gibt einen großen Katalog integrierter Funktionen (truthy, pattern, casing, length, enumeration), und Sie können zu JavaScript wechseln, wenn Sie Logik benötigen, die das deklarative Format nicht ausdrücken kann.
Stärken: Es ist überall, es verfügt über das größte Regel-Ökosystem, Editor-Erweiterungen existieren für VS Code und andere, und es läuft überall, wo Node läuft. Wenn Sie ein Tool wollen, das die gesamte Branche anerkennt, dann ist es dieses. Der Kompromiss besteht darin, dass das Schreiben nicht-trivialer Regeln das Erlernen von JSONPath und schließlich der Funktions-API von Spectral bedeutet. Wir haben eine vollständige Anleitung dazu unter Benutzerdefinierte Spectral-Regeln mit TypeScript erstellen, wenn Sie sich intensiv mit der Erstellung befassen möchten.
Eine minimale .spectral.yaml:
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
Ausführen:
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
Redoclys CLI bündelt Linting mit Bundling und Dokumentations-Vorschau. Ihr Linter liest eine redocly.yaml-Konfiguration, liefert eine Reihe integrierter Regeln und unterstützt konfigurierbare Regelwerke sowie benutzerdefinierte Plugins, die in JavaScript geschrieben sind. Teams, die Redocly bereits für die Dokumentation verwenden, erhalten Linting in derselben Toolchain, ohne eine zusätzliche Abhängigkeit hinzufügen zu müssen, und die integrierten Regeln sind darauf ausgelegt, dass die Dokumente gut gerendert werden.
Stärken: Enge Integration in einen Dokumentations- und Bundling-Workflow, ordentliche Standardeinstellungen und ein Konfigurationsformat, das sich vertraut anfühlt, wenn Sie im Redocly-Ökosystem leben. Falls Sie dort noch nicht etabliert sind, ist die Regelbibliothek kleiner als die von Spectral, und die Dokumentation für benutzerdefinierte Regeln ist weniger umfassend.
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum ist ein neuerer Linter, geschrieben in Go, entwickelt für Geschwindigkeit. Er ist kompatibel mit Spectral-Regelwerken, sodass Sie ihn auf eine bestehende .spectral.yaml richten und dieselben Prüfungen viel schneller auf großen Spezifikationen ausführen können. Für ein Monorepo mit Dutzenden großer API-Dokumente ist der Laufzeitunterschied erheblich.
Stärken: Schnell, Spectral-Regelwerk-kompatibel, einzelne Binärdatei ohne Node-Laufzeitumgebung. Wenn Ihre Spezifikation klein ist, ist der Geschwindigkeitsgewinn unsichtbar, und das Ökosystem sowie die Editor-Tools sind jünger als die von Spectral, daher ist es am attraktivsten als CI-Beschleuniger und nicht als Wahl von Grund auf.
Swagger und openapi-spec-validator
Es lohnt sich, sie zu nennen, damit Sie sie nicht mit Lintern verwechseln. Der Swagger Editor und swagger-cli/openapi-spec-validator prüfen, ob ein Dokument gültiges OpenAPI ist. Das ist nur Gültigkeit, nicht Konsistenz oder Hausstil. Sie werden eine Spezifikation, in der jede Eigenschaft anders benannt ist, problemlos durchlassen, da die OpenAPI-Spezifikation dies nicht verbietet. Validierung ist notwendig, aber sie ist die Basis, nicht die Obergrenze. Wenn Sie zwischen Tools aus der Swagger-Familie und einer vollständigen Designplattform wählen, sind die Kompromisse in Swagger-Alternativen, die auch Ihre API testen dargelegt.
Designzeit-Prüfungen in Apidog
Die oben genannten Tools laufen, nachdem Sie eine Datei erstellt haben. Der andere Ort, um Inkonsistenzen zu erkennen, ist, bevor die Datei existiert, während Sie den Endpunkt entwerfen. Apidog ist eine Design-First-Plattform: Sie erstellen Endpunkte und Datenschemata in einem visuellen Editor, und es hält Ihr Projekt während des gesamten Prozesses intern konsistent. Wiederverwendbare Datenschemata bedeuten, dass dasselbe Modell überall referenziert wird, anstatt pro Endpunkt neu definiert zu werden, was eine ganze Klasse von Namensabweichungen an der Quelle eliminiert. Gemeinsame Antwortkomponenten tun dasselbe für Fehlerformen.
Apidog ist kein direkter Ersatz für ein Spectral-Regelwerk; wenn Sie .spectral.yaml-Regeln committed haben, lassen Sie sie weiterlaufen. Was Apidog ändert, ist, wie viel Ihr Linter überhaupt findet. Wenn die Designoberfläche die Wiederverwendung erzwingt, verwandelt sich der Linter von einer Wand von Verstößen in einen gelegentlichen Fang. Und da Apidog standardmäßiges OpenAPI 3.x importiert und exportiert, ist die Datei, die Sie Spectral oder Vacuum in der CI übergeben, dasselbe Artefakt, sodass die beiden Ebenen sich ergänzen, anstatt zu konkurrieren.
Ein Linter-Setup, das Sie heute ausführen können
Ein gutes Setup führt die Prüfung an drei Stellen aus, jede mit einer anderen Aufgabe. Der Editor gibt sofortiges Feedback. Der Pre-Commit-Hook stoppt offensichtliche Fehler lokal. CI ist das Tor, das niemand umgehen kann. Hier ist jede Ebene.
Ebene 1: Der Editor
Installieren Sie die Spectral VS Code-Erweiterung und fügen Sie eine .spectral.yaml in das Wurzelverzeichnis Ihres Repos hinzu. Die Erweiterung erkennt sie automatisch und unterstreicht Verstöße, während Sie die Spezifikation bearbeiten, so wie ein Tippfehler eine rote Wellenlinie erhält. Dies ist die günstigste mögliche Feedback-Schleife, da der Entwickler das Problem behebt, bevor es überhaupt zu einem Commit wird. Nichts weiter zu konfigurieren; die Datei im Repo ist die einzige Quelle der Wahrheit für die Regeln.
Ebene 2: Pre-Commit
Fügen Sie einen Hook hinzu, damit eine fehlerhafte Spezifikation niemals das Remote erreicht. Ein package.json-Skript plus ein Git-Hook reichen aus:
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (or via husky)
#!/bin/sh
npm run lint:api || {
echo "OpenAPI lint failed. Fix the spec before committing."
exit 1
}
Das Flag --fail-severity=error ist der wichtige Teil. Es weist den Linter an, nur bei Fehlern mit einem Nicht-Null-Wert zu beenden, sodass Warnungen weiterhin ausgegeben werden, ohne den Commit zu blockieren. Das hält den Hook nutzbar, während Sie noch Regeln hochstufen.
Ebene 3: CI
Dies ist das entscheidende Tor, denn es ist dasjenige, das ein Teammitglied nicht mit --no-verify umgehen kann. Ein GitHub Actions-Schritt:
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
Der Job schlägt fehl, wenn die Spezifikation eine Regel auf Fehlerebene verletzt, der Pull Request zeigt ein rotes Häkchen, und der Merge ist blockiert, bis jemand es behebt. Das ist der gesamte Durchsetzungsmechanismus. Keine Dashboards, kein Nörgeln; die Regel ist entweder grün oder nicht.
Ebene 4: Testen Sie die API, die die Spezifikation beschreibt
Ein Linter beweist, dass die Spezifikation gut strukturiert und konsistent ist. Er sagt nichts darüber aus, ob die laufende API der Spezifikation entspricht. Diese Lücke ist der Ort, an dem sich Vertragsabweichungen verbergen: ein wunderschön gelintetes Dokument, das ein Verhalten beschreibt, das der Server vor drei Releases nicht mehr respektierte. Um dies zu schließen, führen Sie Tests gegen die Live-API in derselben Pipeline aus.
Hier passt das Apidog CLI neben Ihren Linter. Es ist ein npm-Paket, apidog-cli, und es führt Ihre Apidog-Testszenarien von der Kommandozeile aus, sodass sie direkt nach dem Lint-Schritt in die CI passen:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
Der Befehl apidog run beendet sich mit einem Nicht-Null-Wert, wenn ein Test fehlschlägt, derselbe Vertrag, auf den jeder CI-Schritt angewiesen ist, sodass ein fehlschlagender Test das Mergen blockiert, genau wie ein fehlschlagendes Linting. Der -r junit-Reporter gibt XML aus, das Ihr CI-Dashboard in einen Bestanden/Nicht bestanden-Baum parst, und -e weist dieselben Szenarien auf Staging oder Produktion, ohne sie zu duplizieren. Das CLI kann auch ein OpenAPI 3.x-Dokument importieren, sodass die Datei, die Ihr Linter prüft, dieselbe Datei ist, gegen die Apidog testet. Für das vollständige Pipeline-Muster, einschließlich Reporter und Umgang mit Exit-Codes, siehe den Leitfaden zum Ausführen des Apidog CLI in Ihrer CI/CD-Pipeline. Wenn Sie speziell GitHub verwenden, bietet das Apidog CLI in GitHub Actions einen Copy-Paste-Workflow.
Zuerst linten, dann testen. Der Lint-Schritt ist schnell und fängt Designprobleme ab; der Test-Schritt ist langsamer und fängt Verhaltensprobleme ab. Führen Sie sie als zwei Phasen aus, und ein Pull Request muss beide bestehen.
Ein Regelwerk schmerzfrei auswählen und übernehmen
Die Auswahl des Tools ist der einfache Teil. Die Einführung bei einer bereits existierenden API ist der Punkt, an dem Teams ins Stocken geraten, denn der erste Lauf auf einer ausgereiften Spezifikation liefert Hunderte von Verstößen, und die offensichtliche Reaktion ist, das Ganze abzuschalten.
Fangen Sie nicht mit null Regeln an und auch nicht mit jeder Regel als Fehler. Beginnen Sie mit dem integrierten Regelwerk (spectral:oas), wobei alles, was Sie hinzufügen, auf warn gesetzt ist. Führen Sie es aus, lesen Sie die Anzahl und beheben Sie zuerst die Gültigkeitsfehler, da dies echte Bugs sind. Wählen Sie dann die zwei oder drei Konsistenzregeln aus, die für Ihre Clients am wichtigsten sind (üblicherweise die Groß-/Kleinschreibung von Eigenschaften und eine einheitliche Fehlerform), und stufen Sie nur diese auf error hoch. Alles andere bleibt eine Warnung. Fördern Sie in jedem Sprint ein oder zwei weitere Warnungen zu Fehlern, sobald die Codebasis aufholt. Innerhalb eines Quartals ist das gesamte Regelwerk durchgesetzt, und niemand musste die Auslieferung stoppen, um dies zu erreichen.
Schreiben Sie Hausstilregeln sparsam. Jede benutzerdefinierte Regel ist Code, den jemand pflegen und dem nächsten Mitarbeiter erklären muss. Eine Regel verdient ihren Platz nur, wenn ein Verstoß Sie tatsächlich getroffen hat, nicht weil er es könnte. Für die Regeln, die Sie schreiben, verlassen Sie sich auf die Designschicht, um sie selten zu machen: Wenn Ihre Schemas aus einer zentralen Definition wiederverwendet werden, wird eine Eigenschafts-Groß-/Kleinschreibungsregel fast nie ausgelöst, da der Name an einer Stelle definiert ist. Die konzeptionelle Einordnung, welche Regeln durchgesetzt werden sollten und welche nur Haarspalterei sind, wird in Best Practices für das API-Design behandelt.
Wenn Sie in einer anderen Sprache als reinem YAML entwerfen, gilt der Linter immer noch. TypeSpec kompiliert zu OpenAPI, und Sie linten das ausgegebene Dokument auf die gleiche Weise; dem Linter ist es egal, wie die Datei erstellt wurde, sondern nur, was sie aussagt.
Wo der Linter in den größeren Design-Zyklus passt
Ein Linter ist ein Kontrollelement in einem Design-First-Workflow, nicht das Ganze. Der vollständige Zyklus ist: den Vertrag entwerfen, ihn linten, ihn mocken, damit Clients darauf aufbauen können, die Implementierung dagegen testen und daraus Dokumente veröffentlichen. Überspringen Sie einen Schritt, verlieren die anderen an Wert. Eine gelintete Spezifikation, die niemand mockt, blockiert immer noch die Frontend-Arbeit. Eine gemockte Spezifikation, die niemand testet, weicht immer noch von der Realität ab.
Der Grund, Design in diesem Zyklus an erster Stelle zu setzen, ist derselbe Grund, warum Linting funktioniert: Probleme dort zu beheben, wo sie am günstigsten sind. Das Ändern eines Eigenschaftsnamens im Design-Tool ist eine einzige Bearbeitung. Das Ändern, nachdem drei Teams mit dem alten Namen gearbeitet haben, ist eine Migration. Der Linter erzwingt Konsistenz auf der Datei; ein Design-First-Prozess erzwingt sie auf der Entscheidung, bevor die Datei existiert. Wenn Sie das breitere Argument für die Reihenfolge wünschen, legt API-First vs. API Design-First vs. Code-First die Kompromisse dar, und Contract-First API Design Tools deckt die unterstützenden Tools ab.
Apidog deckt diesen gesamten Zyklus an einem Ort ab: Entwerfen Sie mit wiederverwendbaren Schemata, mocken Sie sofort, testen Sie mit dem CLI in CI und exportieren Sie sauberes OpenAPI für jeden Linter, auf den Sie sich standardisieren. Der Linter hat immer noch eine Aufgabe; es gibt nur weniger für ihn zu finden.