YAML zum Schreiben
Lange Beschreibungen lesen sich als YAML-Blocktext besser, und mit Kommentaren können Sie die Spezifikation für Reviewer annotieren.
API-Spezifikationen zwischen JSON und YAML konvertieren, ohne $ref-Pfade oder Antwortcodes zu beschädigen.
Jede Zeile der Ausgabe in Standardformatierung neben dem Pfad des Werts, den sie enthält. Klicken Sie auf eine Zeile, um den Pfad zu kopieren.
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.
Zwei Details machen von Hand konvertierte Spezifikationen kaputt: ein #, das einen YAML-Kommentar einleitet, und Statuscodes, die zu Ganzzahlen werden. Beides wird berücksichtigt.
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} 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.
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.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Lange Beschreibungen lesen sich als YAML-Blocktext besser, und mit Kommentaren können Sie die Spezifikation für Reviewer annotieren.
Codegeneratoren, Gateways und SDKs laden JSON oft am schnellsten, und viele stellen die Spezifikation unter /openapi.json bereit.
Beide Formate beschreiben dieselbe API. Konvertieren Sie frei in beide Richtungen; nichts aus der Spezifikation geht verloren.
Konverter, Validatoren und Schritt-für-Schritt-Anleitungen für alle Stellen, an denen JSON und YAML aufeinandertreffen.
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.
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.
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.
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.
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.