YAML for authoring
Long descriptions read better as YAML block text, and comments let you annotate the spec for reviewers.
Convert API specs between JSON and YAML without breaking $ref paths or response codes.
Each line of the output, in default formatting, next to the path of the value it holds. Click a row to copy the path.
Runs entirely in your browser, so nothing is uploaded. Fair-use limits apply (5 MB per input, rate-limited conversions) to prevent spam and bots.
Two details break hand-converted specs: a # that starts a YAML comment, and status codes that become integers. Both are handled.
{
"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 Switch to Hand-written, no quotes to see the $ref turn into null and the wildcard host fail to parse.
After converting, run a linter to check the spec itself, not only its syntax. Here, every local $ref is checked as you edit.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Long descriptions read better as YAML block text, and comments let you annotate the spec for reviewers.
Code generators, gateways and SDKs often load JSON fastest, and many serve the spec at /openapi.json.
Both formats describe the same API. Convert freely in either direction; nothing in the spec is lost.
Converters, validators and step-by-step guides for every place JSON and YAML meet.
Paste or upload openapi.json and copy the YAML from the right-hand pane, or download it as openapi.yaml. The structure, $ref pointers, examples and descriptions are kept exactly.
Yes. The converter works on the document structure, so Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 specs convert the same way, in both directions.
In YAML, # starts a comment when it follows a space. Without quotes, everything after $ref: would be treated as a comment and the reference would be empty. The converter quotes it automatically.
OpenAPI requires response codes to be string keys. An unquoted 200 is an integer in YAML; most tools accept it, but strict validators do not. Quoting keeps the spec valid everywhere.
Switch the direction to YAML → JSON with the toggle above the editor, or use the YAML to JSON converter. Anchors in the YAML are expanded, since JSON has no references of that kind.