OpenAPI & Swagger: JSON zu YAML

API-Spezifikationen zwischen JSON und YAML konvertieren, ohne $ref-Pfade oder Antwortcodes zu beschädigen.

Ausgabeoptionen

JSONEingabe

Leer

YAMLAusgabe

Die YAML-Ausgabe erscheint hier

Läuft vollständig in Ihrem Browser: nichts wird hochgeladen. Es gelten Fair-Use-Limits (5 MB pro Eingabe, begrenzte Anzahl an Konvertierungen), um Spam und Bots zu verhindern.

Von URL laden

Die Datei wird direkt von Ihrem Browser abgerufen, daher muss der Server Cross-Origin-Anfragen zulassen.

Tastenkürzel

Ctrl / ⌘ + Enter Jetzt konvertieren
Ctrl / ⌘ + S Ausgabe herunterladen
Alt + Shift + C Ausgabe kopieren
Alt + Shift + F JSON-Eingabe reparieren und formatieren
Alt + Shift + S Richtung umkehren
Alt + Shift + T Zwischen Code-, Baum- und Zuordnungsansicht wechseln
Ctrl / ⌘ + Z Rückgängig, auch nach Formatieren, Reparieren und Leeren
Esc Vollbild verlassen
Textgröße im Editor

$ref-Zeiger und Antwortcodes bleiben gültig

Zwei Details machen von Hand konvertierte Spezifikationen kaputt: ein #, das einen YAML-Kommentar einleitet, und Statuscodes, die zu Ganzzahlen werden. Beides wird berücksichtigt.

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
paths:
  /pets/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4XX:
          description: Client error

Wechseln Sie zu Von Hand, ohne Anführungszeichen, um zu sehen, wie $ref zu null wird und der Wildcard-Host nicht geparst werden kann.

Das Ergebnis linten

Führen Sie nach dem Konvertieren einen Linter aus, der die Spezifikation selbst prüft, nicht nur ihre Syntax. Hier wird jeder lokale $ref beim Bearbeiten geprüft.

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

JSON oder YAML für API-Spezifikationen?

YAML zum Schreiben

Lange Beschreibungen lesen sich als YAML-Blocktext besser, und mit Kommentaren können Sie die Spezifikation für Reviewer annotieren.

JSON für Tools

Codegeneratoren, Gateways und SDKs laden JSON oft am schnellsten, und viele stellen die Spezifikation unter /openapi.json bereit.

Dasselbe Dokument

Beide Formate beschreiben dieselbe API. Konvertieren Sie frei in beide Richtungen; nichts aus der Spezifikation geht verloren.

Weitere Tools

Konverter, Validatoren und Schritt-für-Schritt-Anleitungen für alle Stellen, an denen JSON und YAML aufeinandertreffen.

Häufig gestellte Fragen

Wie konvertiere ich eine OpenAPI-JSON-Datei in YAML?

Fügen Sie openapi.json ein oder laden Sie die Datei hoch und kopieren Sie das YAML aus dem rechten Bereich, oder laden Sie es als openapi.yaml herunter. Struktur, $ref-Zeiger, Beispiele und Beschreibungen bleiben exakt erhalten.

Funktioniert es für Swagger 2.0 ebenso wie für OpenAPI 3?

Ja. Der Konverter arbeitet auf der Dokumentstruktur, daher werden Swagger 2.0-, OpenAPI 3.0- und OpenAPI 3.1-Spezifikationen gleich konvertiert, in beide Richtungen.

Warum steht $ref: '#/components/...' in Anführungszeichen?

In YAML leitet # einen Kommentar ein, wenn es auf ein Leerzeichen folgt. Ohne Anführungszeichen würde alles nach $ref: als Kommentar behandelt, und der Verweis wäre leer. Der Konverter setzt die Anführungszeichen automatisch.

Warum werden Antwortcodes als '200' geschrieben?

OpenAPI verlangt Antwortcodes als Zeichenketten-Schlüssel. Ein 200 ohne Anführungszeichen ist in YAML eine Ganzzahl; die meisten Tools akzeptieren das, strikte Validatoren aber nicht. Mit Anführungszeichen bleibt die Spezifikation überall gültig.

Wie konvertiere ich OpenAPI-YAML zurück in JSON?

Stellen Sie die Richtung mit dem Umschalter über dem Editor auf YAML → JSON oder verwenden Sie den YAML-zu-JSON-Konverter. Anker im YAML werden aufgelöst, da JSON keine Verweise dieser Art kennt.