Zum Hauptinhalt springen
Bethemesh
Entwicklung

OpenAPI- und Swagger-Validator

Prüfe eine API-Beschreibung in JSON oder YAML ohne Upload.

Füge ein eigenständiges JSON/YAML-Dokument ein oder importiere es und starte die Prüfung. Der Bericht nennt Fehler und den Umfang der Prüfung.

War dieses Werkzeug hilfreich?

Wie funktioniert dieses Tool?

Eine OpenAPI-Beschreibung dient als Vertrag zwischen den Personen, die eine API entwickeln, dokumentieren und nutzen. Falsche YAML-Einrückung, ein fehlendes Pflichtfeld oder eine nicht auflösbare Referenz können ihre Verwendung verhindern. Dieser Validator hilft dir, solche Fehler in JSON oder YAML direkt im Browser zu finden. Er unterstützt Swagger 2.0, OpenAPI 3.0.0–3.0.4 und OpenAPI 3.1.0–3.1.2 im jeweils angegebenen Prüfumfang.

Die Prüfung beginnt mit der Syntax: Der Text muss als einzelnes JSON- oder YAML-Dokument ohne doppelte Schlüssel lesbar sein. Danach werden Version und erwartete Struktur geprüft, darunter API-Informationen und beschriebene Operationen. Auch eine syntaktisch korrekte Datei kann daher das OpenAPI-Schema ihrer Version verletzen.

Interne Referenzen verwenden JSON Pointer wie #/components/responses/Ok, um Stellen im selben Dokument zu bezeichnen. Der Validator prüft ihre Auflösung und unterscheidet echte Referenzen von $ref-Schlüsseln innerhalb von Beispieldaten. Verweise auf andere Dateien oder entfernte Schemas werden abgelehnt; kein Resolver lädt sie herunter.

Zusätzliche Prüfungen betreffen operationIds von Routen und Webhooks, Pfadparameter und die Typen von 3.1-Schemaschlüsselwörtern. Ein positives Ergebnis bleibt eine Teilprüfung: Nicht alle semantischen Bedingungen, Formate und Beispiele werden validiert. Eigene Dialekte, $id, Anker und dynamische Referenzen werden als nicht unterstützt gemeldet.

Ein Diagnosepfad wie /paths/~1health/get/responses bezeichnet das Feld responses von GET /health: In einem JSON Pointer steht ~1 für einen Schrägstrich. Wenn die Stelle im Quelltext auffindbar ist, erscheint eine Zeilennummer. Behebe zuerst die erste eindeutige Ursache, bevor du Folgemeldungen desselben unvollständigen Objekts bearbeitest.

So verwenden Sie dieses Tool

  1. Dokument bereitstellen

    Füge die Beschreibung ein oder importiere eine JSON-, YAML- oder YML-Datei. Fasse Referenzen aus mehreren Dateien vorher zusammen.

  2. Prüfung starten

    Klicke auf Validieren. Die Verarbeitung bleibt in deinem Browser und endet nach spätestens zehn Sekunden.

  3. Gemeldete Pfade korrigieren

    Behebe zuerst Syntaxfehler, korrigiere dann die gemeldeten Felder und prüfe erneut.

Anwendungsfälle

API-Vertrag prüfen

Kontrolliere eine Datei vor dem Commit oder der Weitergabe an andere Entwickler.

Export untersuchen

Finde Strukturfehler in Beschreibungen, die ein Framework oder Generator erzeugt hat.

Private API untersuchen

Prüfe interne Beschreibungen ohne Upload und ohne Aufruf der beschriebenen Endpunkte.

Beispiele

Ein eigenständiges Dokument mit interner Referenz

Füge dieses vollständige Dokument ein, um GET /health zu beschreiben. Die Antwort 200 verwendet die Komponente Ok aus derselben Datei. Geprüft wird eine Vertragsbeschreibung; keine GET-Anfrage geht an einen Server.

Eingabe

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Ok"
components:
  responses:
    Ok:
      description: OK

Ergebnis

Im geprüften Umfang gültig
Definierte HTTP-Operationen: 1

Ein fehlendes Pflichtfeld

Dieses YAML ist lesbar, aber info.version fehlt. Ergänze beispielsweise version: 1.0.0 innerhalb von info. Ein leeres paths-Objekt ist für sich genommen nicht die Fehlerursache. Die angezeigte Zeile hängt von der Position des Feldes in deiner Datei ab.

Eingabe

openapi: 3.1.0
info:
  title: Health API
paths: {}

Ergebnis

Beschreibung muss korrigiert werden
Pfad: /info
Struktur entspricht nicht der Spezifikation.
Detail: required: version

Eine nicht auflösbare interne Referenz

Das Dokument enthält weiterhin die Komponente Ok, die Antwort verlangt aber Absent. Korrigiere den Namen in der Referenz. Ersetzt du ihn durch eine externe URL, wird stattdessen eine abgelehnte externe Referenz gemeldet. Die entfernte Datei wird nicht geladen.

Eingabe

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Absent"
components:
  responses:
    Ok:
      description: OK

Ergebnis

Beschreibung muss korrigiert werden
Pfad: /paths/~1health/get/responses/200/$ref
Interner Verweis nicht gefunden.

Tipps und bewährte Vorgehensweisen

  • info.version bezeichnet die Version deiner API; openapi nennt die Version des Beschreibungsformats. Beide Angaben sind nicht austauschbar.
  • Ein Pfad /users/{id} muss den Parameter id am Pfad oder an der Operation deklarieren. Ein Abfrageparameter namens id ersetzt keinen Pfadparameter.
  • Fasse mehrere Dateien zuerst mit deinem üblichen Bündelungswerkzeug zu einem eigenständigen Dokument zusammen. Die Eingabe ist auf eine Million Zeichen begrenzt, auch YAML-Aliase und Komplexität sind begrenzt. Nach zehn Sekunden endet die Prüfung spätestens.

Quellen und Referenzen

Häufig gestellte Fragen

Beweist eine erfolgreiche Prüfung, dass die API funktioniert?

Nein. Der Validator prüft Teile der Beschreibung, keine Serverantworten, Zugriffsrechte oder Geschäftsregeln. Kein Endpunkt wird aufgerufen. Der Bericht erklärt die Grenzen der Prüfung.

Wie prüfe ich mehrere zusammengehörige Dateien?

Fasse sie mit deinen lokalen Werkzeugen zu einem eigenständigen Dokument zusammen. Verknüpfte Dateien werden nicht geladen.

Wird OpenAPI 3.2 unterstützt?

In dieser Version noch nicht. Nicht unterstützte Versionen werden ausdrücklich gemeldet und nicht als Syntaxfehler behandelt.

Was wird geprüft?

Das Dokument wird gegen das Strukturschema seiner Version geprüft. Hinzu kommen interne JSON-Pointer-Referenzen, Schlüsselworttypen von 3.1-Schemas, operationIds von Routen und Webhooks sowie Pfadparameter. Formate, Beispiele, echte Daten und weitere semantische Bedingungen werden nicht vollständig geprüft.

Verwandte Werkzeuge

Mit diesen Werkzeugen weitermachen

Werkzeuge, die diesem ähnlich sind oder es ergänzen.

Ähnliche Werkzeuge

JSON-Schema validieren

Prüft JSON-Dokumente gegen ein JSON Schema und zeigt Fehler mit Pfad und Regel präzise an.

EntwicklungEmpfohlenDieses Werkzeug verwenden

API-Anfrage-Builder

Eine vollständige HTTP-API-Anfrage mit Methode, URL, Parametern, Headern und Body erstellen.

EntwicklungDieses Werkzeug verwenden