Dieser OpenAPI-Viewer und -Validator liest ein OpenAPI-3.0-, 3.1- oder Swagger-2.0-Dokument in YAML oder JSON und zeigt es als durchsuchbare API-Dokumentation an: jeder Endpunkt nach Tag gruppiert, mit Parametern, Request-Body, Responses und Schemas, dazu ein sofort ausführbarer cURL-Befehl. Füge die Spezifikation ein oder öffne die Datei; nichts wird hochgeladen, interne und unveröffentlichte APIs bleiben also privat.
Der Validator führt 23 Strukturprüfungen aus den Spezifikationen aus, die alle auf der Seite aufgelistet sind: info und paths vorhanden, Responses mit Beschreibung und gültigen Statuscodes, jeder {parameter} in einem Pfad als erforderlicher Pfadparameter deklariert, eindeutige operationIds, auflösbare $refs und Security-Anforderungen, die ein definiertes Scheme nennen. Das sind die Fehler, an denen Codegeneratoren und Dokumentationstools scheitern. Es ist keine vollständige Validierung gegen das offizielle JSON Schema der Spezifikation, eine Spezifikation, die hier besteht, kann also zum Beispiel noch ein falsch geschriebenes Schema-Keyword enthalten. Externe $refs auf andere Dateien werden aufgelistet, aber nicht abgerufen.
So funktioniert’s
- Füge deine openapi.yaml, openapi.json oder swagger.json ein oder öffne die Datei. Zum Start ist eine Beispiel-API geladen.
- Lies die Statuszeile und die Liste unter „Validierung“. Jedes Problem nennt die Regel und die Stelle (zum Beispiel paths./pets/{id}.get).
- Durchsuche die Dokumentation: Operationen sind nach Tag gruppiert; klick auf eine, um Parameter, Request-Body, Responses und Schemas zu sehen.
- Filtere nach Pfad, summary oder operationId, um einen Endpunkt in einer großen Spezifikation zu finden.
- Kopiere das cURL-Beispiel einer Operation und ersetze den Platzhalter <TOKEN> oder <API_KEY> durch deine Zugangsdaten.
Häufige Fragen
Wie zeige ich eine Swagger- oder OpenAPI-Datei an?
Füge das YAML oder JSON in das Feld ein oder öffne die Datei. Der Viewer erkennt die Version (swagger: "2.0" oder openapi: 3.0.x / 3.1.x), listet die Endpunkte nach Tag gruppiert auf und lässt dich jeden aufklappen, um Parameter, Request-Body, Responses und aufgelöste Schemas zu sehen. Sobald die Seite geladen ist, funktioniert er auch offline.
Was prüft der OpenAPI-Validator?
Strukturregeln aus der Spezifikation: ein unterstütztes Versionsfeld; info mit title und version; Pfade, die mit / beginnen; Operationen mit nicht leeren responses, die eine description und gültige Statuscodes haben; deklarierte und erforderliche Parameter für Pfadvorlagen; Parameter mit name, einem gültigen in und einem schema; keine doppelten Parameter oder operationIds; Request-Bodys mit content; auflösbare $refs; und Security-Anforderungen, die definierte Schemes nennen. Die vollständige Liste steht auf der Seite unter „Was geprüft wird“. Nicht jedes Schema-Keyword wird gegen das offizielle JSON Schema validiert.
Warum ist mein nicht deklarierter Pfadparameter ein Fehler?
Die Spezifikation verlangt, dass jeder {name} in einer Pfadvorlage einen passenden Parameter mit in: path und required: true hat, auf Pfad- oder Operationsebene. Manche Validatoren, die das Dokument nur gegen das JSON Schema prüfen, akzeptieren einen fehlenden, aber Codegeneratoren erzeugen dann eine Funktion ohne Argument dafür, und Dokumentationstools zeigen einen Endpunkt, den man nicht korrekt aufrufen kann.
Kann der Viewer OpenAPI 3.1 und Swagger 2.0 lesen?
Ja. Parameter vom Typ body und formData aus Swagger 2.0 werden als Request-Body angezeigt, mit produces und consumes als Medientypen, sodass alle drei Versionen gleich gelesen werden. Unterschiede in OpenAPI 3.1 werden berücksichtigt: paths ist optional, wenn components oder webhooks vorhanden sind, responses ist optional (hier eine Warnung), und type: [string, "null"] wird als nullable angezeigt.
Lädt der Viewer externe $ref-Dateien?
Nein. Ein $ref auf eine andere Datei oder URL (zum Beispiel ./schemas/user.yaml) wird als Warnung aufgeführt und als nicht aufgelöst angezeigt, weil die Seite keine Dateien lesen kann, die du nicht geöffnet hast, und keine URLs von sich aus abruft. Fasse eine Spezifikation aus mehreren Dateien zuerst zu einem Dokument zusammen, zum Beispiel mit redocly bundle oder swagger-cli bundle.
Wird meine API-Spezifikation hochgeladen?
Nein. Parsen, Validieren und Darstellen laufen in deinem Browser. Die Spezifikation wird nirgendwohin gesendet.
OpenAPI 3.x und Swagger 2.0: was sich geändert hat
• Versionsfeld: Aus swagger: "2.0" wurde openapi: 3.0.x, dann 3.1.x.
• Server: 2.0 hat host, basePath und schemes; 3.x hat eine servers-Liste mit Variablen.
• Request-Bodys: 2.0 verwendet einen Parameter mit in: body (oder formData); 3.x hat requestBody mit content pro Medientyp.
• Wiederverwendbare Teile: In 2.0 stehen definitions, parameters und responses auf oberster Ebene; 3.x legt sie unter components ab, neben securitySchemes, requestBodies und examples.
• 3.1 gleicht Schemas an JSON Schema 2020-12 an: type kann eine Liste sein (["string", "null"] statt nullable: true), examples ist ein Array, und webhooks kommen hinzu.
Die Fehler, die API-Tools am häufigsten lahmlegen
• Pfadparameter, die nicht deklariert sind oder ohne required: true deklariert sind.
• Ein $ref mit Tippfehler (#/components/schema/User statt schemas), wodurch ein Teil der Doku leer bleibt.
• Doppelte operationIds, an denen Codegeneratoren scheitern oder durch die Methoden überschrieben werden.
• Responses ohne description (sie ist Pflicht, auch wenn sie nur "OK" lautet).
• Eine Security-Anforderung, die ein nicht definiertes Scheme nennt, sodass sich der generierte Client nicht authentifizieren kann.
