OpenAPI & Swagger JSON to YAML

Convert API specs between JSON and YAML without breaking $ref paths or response codes.

Output options

JSONinput

Empty

YAMLoutput

YAML output appears here

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.

Load from URL

The file is fetched directly by your browser, so the server must allow cross-origin requests.

Keyboard shortcuts

Ctrl / ⌘ + Enter Convert now
Ctrl / ⌘ + S Download the output
Alt + Shift + C Copy the output
Alt + Shift + F Fix and format the JSON input
Alt + Shift + S Swap direction
Alt + Shift + T Cycle through code, tree and map views
Ctrl / ⌘ + Z Undo, including Format, Fix and Clear
Esc Leave full screen
Editor text size

$ref pointers and response codes stay valid

Two details break hand-converted specs: a # that starts a YAML comment, and status codes that become integers. Both are handled.

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

Switch to Hand-written, no quotes to see the $ref turn into null and the wildcard host fail to parse.

Lint the result

After converting, run a linter to check the spec itself, not only its syntax. Here, every local $ref is checked as you edit.

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

JSON or YAML for API specs?

YAML for authoring

Long descriptions read better as YAML block text, and comments let you annotate the spec for reviewers.

JSON for tooling

Code generators, gateways and SDKs often load JSON fastest, and many serve the spec at /openapi.json.

Same document

Both formats describe the same API. Convert freely in either direction; nothing in the spec is lost.

More tools

Converters, validators and step-by-step guides for every place JSON and YAML meet.

Frequently asked questions

How do I convert an OpenAPI JSON file to YAML?

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.

Does it work for Swagger 2.0 as well as OpenAPI 3?

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.

Why is $ref: '#/components/...' quoted?

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.

Why are response codes written as '200'?

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.

How do I convert OpenAPI YAML back to JSON?

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.