Zum Inhalt springen

OpenAPI- & Swagger-Viewer und -Validator — YAML oder JSON

Füge eine OpenAPI-3.x- oder Swagger-2.0-Spezifikation ein, um sie als nach Tags gruppierte Doku zu durchsuchen, auf Strukturfehler zu prüfen und für jeden Endpunkt ein cURL-Beispiel zu erhalten.

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 Operationen · 1 Fehler, 0 Warnungen

Validierung

  • Fehler Der Pfad verwendet {itemId}, aber es ist kein Parameter mit in: path namens „itemId“ deklariert.
    bei paths./orders/{orderId}/items/{itemId}.get
Was geprüft wird

Der Viewer prüft diese Strukturregeln aus den Spezifikationen OpenAPI 3.0 / 3.1 und Swagger 2.0. Das ist keine vollständige JSON-Schema-Validierung des Dokuments: Einzelne Schema-Keywords (minimum, pattern, format…) werden nicht geprüft.

  • Das Dokument ist gültiges YAML oder JSON.
  • Es deklariert openapi: 3.0.x oder 3.1.x oder swagger: "2.0".
  • info existiert mit title und version (Strings).
  • paths existiert (in 3.1 optional, wenn components oder webhooks vorhanden sind).
  • Jeder Pfad beginnt mit /.
  • Path Items enthalten nur HTTP-Methoden, parameters, $ref, summary, description, servers (oder x-Erweiterungen).
  • Jede Operation hat responses (in 2.0 und 3.0 ein Fehler, in 3.1 eine Warnung).
  • responses ist nicht leer.
  • Response-Keys sind Statuscodes (200), default oder (3.x) Bereiche wie 2XX.
  • Jede Response hat eine description.
  • operationId-Werte sind eindeutig.
  • Jeder {name} in einem Pfad hat einen passenden Parameter mit in: path.
  • Jeder Parameter mit in: path kommt im Pfad vor.
  • Pfadparameter haben required: true.
  • Jeder Parameter hat name und in.
  • in ist query, header, path oder cookie (2.0: query, header, path, formData oder body).
  • Kein Parameter ist zweimal mit gleichem name und in aufgeführt.
  • Parameter haben ein schema oder content (2.0: body-Parameter haben ein schema, andere einen type).
  • 2.0: höchstens ein body-Parameter, und nicht zusammen mit formData.
  • 3.x: requestBody hat content.
  • Jeder lokale $ref (#/…) verweist auf etwas, das existiert.
  • Verweise auf andere Dateien oder URLs werden gemeldet (sie werden nicht abgerufen).
  • Security-Anforderungen nennen ein definiertes Security Scheme.

Dokumentation: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

Basis-URL: https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

Schemas

NewBook
Book
Author
OrderItem

Läuft vollständig in deinem Browser. Deine API-Spezifikation wird nie hochgeladen, und externe $refs werden nicht abgerufen. Alle kostenlosen Tools ansehen.

Ein Problem gefunden oder etwas, das besser sein könnte? Wir lesen jede Nachricht und beheben Fehler schnell.

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

  1. Füge deine openapi.yaml, openapi.json oder swagger.json ein oder öffne die Datei. Zum Start ist eine Beispiel-API geladen.
  2. Lies die Statuszeile und die Liste unter „Validierung“. Jedes Problem nennt die Regel und die Stelle (zum Beispiel paths./pets/{id}.get).
  3. Durchsuche die Dokumentation: Operationen sind nach Tag gruppiert; klick auf eine, um Parameter, Request-Body, Responses und Schemas zu sehen.
  4. Filtere nach Pfad, summary oder operationId, um einen Endpunkt in einer großen Spezifikation zu finden.
  5. 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.