OpenAPI-Validator: API-Spec prüfen

Was ist der OpenAPI-Validator?

Der OpenAPI-Validator ist ein browserbasiertes Tool, das OpenAPI 3.x- und Swagger 2.0-Spezifikationsdateien parst und validiert. Fügen Sie eine JSON- oder YAML-Spec ein, klicken Sie auf „Validate", und innerhalb von Sekunden sehen Sie, ob die Spec strukturell gültig ist, eine Anzahl der Pfade und Operationen sowie eine Liste von Warnungen für fehlende Felder, die für SDK-Generatoren und Entwicklerdokumentations-Tools wichtig sind.

Das Tool läuft vollständig in Ihrem Browser mit der @readme/openapi-parser-Bibliothek, die bei Bedarf geladen wird. Kein Spec-Inhalt wird an einen Server gesendet. Es ist kostenlos nutzbar ohne erforderliches Konto.

Verwenden Sie es vor dem Committen einer Spec in die Versionskontrolle, vor der Veröffentlichung von API-Dokumentation oder beim Debuggen einer Spec, die ein nachgelagertes Tool wie Swagger UI, Stoplight oder ein SDK-Generator ablehnt.

Hauptfunktionen

• OpenAPI 3.x und Swagger 2.0 Unterstützung: Der Validator akzeptiert beide Formate. Die zugrunde liegende @readme/openapi-parser-Bibliothek verarbeitet beide Spezifikationsversionen, einschließlich OpenAPI 3.1.
• JSON- und YAML-Eingabe: Das Tool versucht zuerst JSON.parse, dann fällt es auf js-yaml für YAML-Eingabe zurück. Sie müssen nicht angeben, welches Format Sie verwenden.
• Strukturelle Validierung mit präzisen Fehlermeldungen: Wenn die Validierung fehlschlägt, werden Fehlermeldungen des Parsers an Zeilenumbrüchen aufgeteilt und einzeln angezeigt, jeweils mit einer Pfadreferenz, wo zutreffend.
• Linting-Warnungen: Auch wenn eine Spec strukturell gültig ist, prüft das Tool auf drei häufige Qualitätsprobleme: fehlende info.description, Operationen ohne description und summary, und Operationen ohne operationId (erforderlich für SDK-Generierung). Jede Warnung zeigt eine Anzahl, damit Sie den Umfang des Problems kennen.
• Endpoint- und Operations-Zähler: Nach einer erfolgreichen Validierung zeigen Zusammenfassungskacheln den API-Titel, die Versionszeichenfolge, die Gesamtanzahl der Pfade und die Gesamtanzahl der Operationen (über alle HTTP-Methoden: get, post, put, patch, delete, head, options, trace).
• Beispiel laden-Button: Fügt eine minimale, aber vollständige OpenAPI 3.0 Spec mit einem einzelnen /users GET-Endpoint ein, damit Sie sehen können, wie gültige Ausgabe aussieht, bevor Sie Ihre eigene Spec einfügen.
• Validierungsverlauf: Frühere Specs werden in der IndexedDB-Datenbank des Browsers gespeichert (Supporter-Funktion), sodass Sie sie erneut aufrufen oder wiederherstellen können, ohne sie erneut einzufügen.
• 100% clientseitige Verarbeitung: Parser und Validator laufen im Browser. Spec-Inhalte verlassen niemals Ihren Rechner.

So verwenden Sie den OpenAPI-Validator

Schritt 1: Spec einfügen

Klicken Sie in das große Textfeld mit der Bezeichnung „OpenAPI Specification (JSON or YAML)" und fügen Sie Ihren Spec-Inhalt ein. Das Feld akzeptiert rohes YAML oder JSON. Für YAML fügen Sie die Versionsdeklaration oben ein (openapi: "3.0.0" oder swagger: "2.0"). Das Textfeld ist in Monospace und zeigt ungefähr 15-20 sichtbare Zeilen.

Wenn Sie das Tool in Aktion sehen möchten, bevor Sie Ihre eigene Spec verwenden, klicken Sie auf den „Load Example"-Button in der oberen rechten Ecke des Textfelds. Er lädt eine minimale OpenAPI 3.0 Spec mit einem /users GET-Endpoint, der ein Array von Benutzerobjekten zurückgibt.

Schritt 2: „Validate Spec" klicken

Klicken Sie auf den „Validate Spec"-Button unter dem Textfeld. Der Button zeigt „Validating..." an, während der Parser läuft (die @readme/openapi-parser- und js-yaml-Bibliotheken werden beim ersten Gebrauch dynamisch geladen, sodass die erste Validierung etwas länger dauern kann als nachfolgende).

Die Validierung wird gegen die vollständige Spec im Speicher ausgeführt. Für YAML-Eingabe konvertiert das Tool sie zuerst mit js-yaml in ein JavaScript-Objekt und übergibt dann das Objekt an den OpenAPI-Parser.

Schritt 3: Validierungsergebnis überprüfen

Das Ergebnispanel erscheint unter dem Button mit einer von zwei Überschriften:

• „✓ Valid OpenAPI Specification" in Grün — die Spec hat die strukturelle Validierung bestanden.
• „✗ Validation Failed" in Rot — die Spec hat strukturelle Fehler, die behoben werden müssen.

Die Panel-Überschrift zeigt auch Badge-Zähler: rote Badges für Fehler, gelbe Badges für Warnungen. Sie können eine gültige Spec mit Warnungen haben — Warnungen zeigen Qualitätsverbesserungen an, keine strukturellen Fehler.

Schritt 4: Zusammenfassungskacheln lesen (gültige Specs)

Für Specs, die die Validierung bestehen, erscheinen vier Zusammenfassungskacheln über der Fehler-/Warnungsliste:

• Title — der Wert von info.title
• Version — der Wert von info.version
• Paths — Gesamtanzahl der Pfadeinträge (z. B. /users, /users/{id})
• Operations — Gesamtanzahl der HTTP-Methode+Pfad-Kombinationen (z. B. ein Pfad mit GET und POST zählt als 2)

Diese Zahlen sind nützlich zur Bestätigung, dass Sie die richtige Datei validieren, besonders bei der Verwaltung mehrerer Spec-Versionen.

Schritt 5: Warnungen beheben

Drei Warnungstypen werden auch bei gültigen Specs angezeigt:

1. Fehlende info.description — der Spec fehlt eine allgemeine API-Beschreibung. Diese erscheint in Swagger UI und Entwicklerportalen und hilft Benutzern zu verstehen, was die API tut.
2. Operationen ohne description oder summary — als Anzahl gemeldet (z. B. „3 operation(s) missing description or summary"). Sowohl description als auch summary werden geprüft; wenn einer vorhanden ist, wird keine Warnung für diese Operation ausgelöst.
3. Operationen ohne operationId — SDK-Generatoren (OpenAPI Generator, Kiota usw.) verwenden operationId zur Benennung generierter Methoden. Fehlende Werte führen dazu, dass Generatoren auf pfadbasierte Namen zurückfallen, die oft umständlich und inkonsistent sind.

Praktische Beispiele

Beispiel 1: Ein fehlendes Pflichtfeld finden

Angenommen, Sie fügen eine Swagger 2.0 Spec ein, die eine $ref referenziert, die auf eine nicht existierende Schema-Definition zeigt. Der Validator wird zurückgeben:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Jede Zeile der Parser-Fehlermeldung wird als separater Fehlereintrag angezeigt. Korrigieren Sie den $ref-Pfad oder fügen Sie die fehlende Definition hinzu, dann validieren Sie erneut.

Beispiel 2: Gültige Spec mit Qualitätswarnungen

Eine Spec mit allen erforderlichen strukturellen Elementen, aber ohne operationId-Werte an ihren Endpoints, besteht die Validierung, zeigt aber:

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

Die Spec kann sofort in Tools wie Swagger UI verwendet werden. Beheben Sie die Warnungen, bevor Sie sie durch einen SDK-Generator laufen lassen.

Beispiel 3: Eine große Spec auf einen Blick prüfen

Nach dem Einfügen einer internen API-Spec mit 500 Pfaden zeigen die Zusammenfassungskacheln „Paths: 147" und „Operations: 312". Wenn Sie 150 Pfade erwartet haben, wissen Sie, dass Sie untersuchen müssen, warum drei Pfade fehlen, bevor Sie die Spec committen.

Tipps und Best Practices

Validieren Sie nach jeder strukturellen Änderung. Das Hinzufügen eines neuen Pfads, das Ändern einer $ref oder das Modifizieren eines Schemas kann Fehler einführen, die erst beim Parsen der vollständigen Spec erscheinen. Die Validierung dauert unter zwei Sekunden, führen Sie sie also häufig aus.

Behandeln Sie operationId-Warnungen als Blocker für SDK-Workflows. Wenn Sie Client-SDKs aus Ihrer Spec generieren, müssen alle Operationen eindeutige operationId-Werte haben. Werden sie nicht gesetzt, werden generierte Methodennamen von Pfaden abgeleitet (z. B. getUsersUserIdOrders statt listOrders), was schwer handhabbar ist.

Verwenden Sie das Beispiel als Vorlage. Das eingebaute Beispiel ist eine vollständige, gültige, minimale OpenAPI 3.0 Spec. Kopieren Sie es aus dem Textfeld nach dem Laden und verwenden Sie es als Gerüst für eine neue Spec, anstatt von einer leeren Datei zu beginnen.

Trennen Sie strukturelle Gültigkeit von semantischer Korrektheit. Der Validator bestätigt, dass Ihre Spec dem OpenAPI-Schema folgt. Er bestätigt nicht, dass Ihre Spec Ihre tatsächliche API korrekt beschreibt. Führen Sie Integrationstests oder Contract-Tests durch, um die semantische Genauigkeit zu verifizieren.

Beheben Sie Fehler von oben nach unten. Eine einzelne fehlende Schema-Definition kann kaskadierende $ref-Fehler in der gesamten Spec verursachen. Beheben Sie den Ursachenfehler zuerst und validieren Sie erneut, bevor Sie sekundäre Fehler bearbeiten.

Häufige Probleme und Fehlerbehebung

„Parse error: ..." — die Eingabe ist weder gültiges JSON noch gültiges YAML. Häufige Ursachen: ein nachgestelltes Komma in JSON ({"key": "value",}), inkonsistente YAML-Einrückung oder ein Tabulator für YAML-Einrückung (YAML erfordert Leerzeichen). Korrigieren Sie die Syntax und validieren Sie erneut.

Validierung schlägt bei einer Spec fehl, die Swagger UI akzeptiert. Swagger UI ist tolerant und rendert Specs mit einigen strukturellen Verletzungen. Der @readme/openapi-parser wendet strenge Validierung gemäß dem offiziellen JSON-Schema für OpenAPI an. Die hier gezeigten Fehler spiegeln echte Spezifikationsverletzungen wider, auch wenn Swagger UI sie stillschweigend ignoriert.

Warnungen erscheinen auch nach dem Hinzufügen von Beschreibungen. Das Tool prüft sowohl description als auch summary bei Operationen, prüft info.description aber separat. Bestätigen Sie, dass Sie description innerhalb von info hinzugefügt haben, nicht nur bei einzelnen Pfaden.

Das Tool scheint bei der ersten Verwendung langsam. Die @readme/openapi-parser- und js-yaml-Bibliotheken werden beim ersten Validierungs-Klick dynamisch geladen. Nachfolgende Validierungen in derselben Browser-Sitzung sind schneller, da die Module bereits im Speicher sind.

Lange Fehlermeldungen werden abgeschnitten. Fehlermeldungen des Parsers werden vollständig angezeigt. Wenn eine Nachricht lang ist, bricht der Text innerhalb seiner Zeile um. Scrollen Sie die Seite, um die vollständige Nachricht zu lesen, wenn sie über den sichtbaren Bereich hinausgeht.

Datenschutz und Sicherheit

Der OpenAPI-Validator verarbeitet Ihre Spec vollständig im Browser. Die @readme/openapi-parser-Bibliothek läuft lokal — kein Spec-Inhalt wird an einen externen Dienst oder Server gesendet. Das bedeutet, Sie können interne API-Specs, private Endpoint-Pfade und proprietäre Schema-Definitionen sicher validieren, ohne Risiko einer Offenlegung. Das Tool funktioniert vollständig offline, sobald die Seite und die Parser-Bibliothek geladen sind.

Häufig gestellte Fragen

Ist der OpenAPI-Validator kostenlos? Ja. Es gibt keine Kosten, kein Konto und keine Nutzungsbeschränkung. Alle Validierungsfunktionen sind ohne Anmeldung verfügbar.

Welche OpenAPI-Versionen werden unterstützt? Das Tool akzeptiert Swagger 2.0, OpenAPI 3.0.x und OpenAPI 3.1.x. Der zugrunde liegende @readme/openapi-parser verarbeitet alle drei Versionen. Der Textfeld-Platzhalter liest „OpenAPI 2.0 / 3.0 / 3.1", um dies widerzuspiegeln.

Kann ich YAML einfügen oder muss es JSON sein? Beide Formate funktionieren. Das Tool versucht zuerst JSON.parse, und wenn das fehlschlägt, verwendet es js-yaml zum Parsen von YAML. Sie müssen Ihre Spec vor dem Einfügen nicht konvertieren.

Validiert das Tool meine tatsächlichen API-Endpoints? Nein. Der Validator prüft, ob Ihre Spec-Datei gemäß dem OpenAPI-Schema strukturell korrekt ist. Er führt keine HTTP-Anfragen an die in Ihrer Spec aufgelisteten Server oder Pfade aus.

Warum schlägt meine Spec hier fehl, funktioniert aber in Swagger UI? Swagger UI rendert Specs mit einer gewissen Toleranz für Fehler. Dieser Validator wendet strenge Schema-Validierung an, die Probleme erkennt, die Swagger UI stillschweigend ignoriert. Beide Verhaltensweisen sind beabsichtigt — dieses Tool erkennt Spec-Qualitätsprobleme früh, bevor sie in strikteren Konsumenten wie SDK-Generatoren Probleme verursachen.

Was bedeutet „operationId required for SDK generation"? SDK-Generatoren wie OpenAPI Generator und Kiota benennen generierte Methoden nach operationId-Werten. Ohne sie greifen Generatoren auf die Konstruktion von Namen aus HTTP-Methode und Pfad zurück (z. B. getApiV1UsersUserIdOrdersOrderId). Das Hinzufügen prägnanter, eindeutiger operationId-Werte zu jeder Operation erzeugt wesentlich saubereren generierten Client-Code.

Gibt es Fehlalarme bei den Warnungen? Die drei Warnungsprüfungen sind konservativ. Die info.description-Prüfung wird nur ausgelöst, wenn das Feld fehlt oder leer ist. Die Prüfung der Operations-Beschreibung zählt nur Operationen, denen sowohl description als auch summary fehlen — wenn eines vorhanden ist, wird die Warnung für diese Operation unterdrückt. Die operationId-Prüfung ist streng: jede Operation ohne eine wird gezählt.

Kann ich eine Spec-Datei validieren, anstatt sie einzufügen? Das Tool akzeptiert nur eingefügten Text — es gibt keinen Datei-Upload-Button. Öffnen Sie Ihre Spec-Datei in einem Texteditor, wählen Sie alles aus und fügen Sie den Inhalt in das Textfeld ein.

Speichert das Verlaufspanel meinen Spec-Inhalt? Ja. Wenn Sie eine Spec erfolgreich validieren, speichert das Tool einen Eintrag im IndexedDB-Verlauf Ihres Browsers (Supporter-Funktion), der die eingegebene Spec und die Validierungszusammenfassung enthält. Der Verlauf ist lokal in Ihrem Browser und wird niemals mit einem Server synchronisiert.

Was passiert, wenn ich eine leere Spec einfüge? Der Validate-Button ist deaktiviert, wenn das Textfeld leer ist (disabled={!input.trim()}). Sie müssen mindestens ein Nicht-Leerzeichen eingeben, bevor der Button klickbar wird.

Verwandte Tools

• Demnächst verfügbar: API-Mock-Generator — generieren Sie Mock-Antwortdaten aus Ihrer validierten Spec zur Verwendung in der Frontend-Entwicklung.
• Demnächst verfügbar: API-Design-Suite — entwerfen und iterieren Sie an der API-Struktur, bevor Sie in das OpenAPI-Format exportieren.
• JSON-Formatierer — formatieren und validieren Sie die JSON-Struktur Ihrer Spec, bevor Sie sie in den Validator einfügen.

Testen Sie den OpenAPI-Validator jetzt: OpenAPI-Validator