OpenAPI JSON Validator

Häufige JSON-Fehler, die eine Prüfung scheitern lassen

JSON ist strenger als YAML. Deshalb liegen die meisten Fehler in einer von Hand bearbeiteten Datei an der Syntax und nicht am API-Design. Typische Ursachen sind ein Komma nach der letzten Eigenschaft, einfache statt doppelter Anführungszeichen, ein Kommentar (JSON erlaubt keine) oder eine fehlende schließende geschweifte Klammer nach einem langen paths-Objekt. Eine kaputte Datei endet meist mit der Meldung „Konnte nicht als JSON oder YAML gelesen werden“ oder mit Fehlern zu fehlenden Feldern, weil nichts Verwertbares gelesen wurde.

Wenn Sie nur einen Parserfehler sehen, suchen Sie zuerst den Syntaxfehler. Die Strukturprüfungen laufen erst, wenn das Dokument als Objekt gelesen wird.

Ein Beispiel

Nehmen Sie dieses kleine Dokument:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Es lässt sich lesen, das Feld openapi und das Objekt paths sind vorhanden. Der Bericht würde dennoch zeigen:

Da ein Fehler vorliegt, wird das Dokument nicht als gültig gemeldet. Ergänzen Sie "version": "1.0.0" in info und benennen Sie den Schlüssel in /orders um. Ein zweiter Durchlauf entfernt beide Befunde.

Was ein Bestehen bedeutet und was nicht

Ein sauberer Bericht bedeutet, dass das Grundgerüst stimmt. Er folgt keinen $ref-Verweisen, prüft keine Schemas und bestätigt nicht, dass jede Operation Antworten hat. Betrachten Sie das Ergebnis als schnelles Tor vor dem Commit der Datei und führen Sie für tiefergehende Regeln einen vollständigen Linter aus.

Ein praktischer Ablauf für JSON-Spezifikationen

Halten Sie die Spezifikation unter Versionskontrolle und fügen Sie sie hier vor jedem Commit ein, der paths ändert. Da die Prüfung schnell ist, eignet sie sich als Plausibilitätsschritt nach dem Zusammenführen von Änderungen mehrerer Personen, wenn doppelte Schlüssel oder eine verrutschte Klammer am wahrscheinlichsten sind. Wenn Ihr JSON von einem Build-Skript erzeugt wird, fügen Sie die erzeugte Ausgabe statt der Vorlage ein, damit Sie testen, was Leser tatsächlich erhalten. Ist der Bericht sauber, können Sie die Datei teilen oder an einen Dokumentationsgenerator übergeben und darauf vertrauen, dass die oberste Struktur stimmt.