OpenAPI YAML to JSON Converter (and Back)

Most OpenAPI (formerly “Swagger”) specs get hand-authored in YAML — comments, multi-line descriptions, and none of JSON's bracket-and-comma punctuation make it the format people actually want to type. But a lot of downstream tooling — codegen for client SDKs, some API gateways, certain linters — expects JSON, or at least behaves more predictably against it. That's the first reason to reach for an OpenAPI YAML to JSON converter (people searching for the same tool often call it a swagger formatter): converting one direction or the other so the same source of truth works with both a human editing it and a machine consuming it.

The second reason is plainer: a spec that's grown for a year across a dozen contributors accumulates inconsistent indentation, mixed quoting, and — the subject of the section below — keys added in whatever order whoever was editing that day happened to type them. Reformatting fixes the presentation; it does not touch what the spec says. A tool that converts and re-indents a spec is not the same tool as one that checks the spec is correct — that distinction matters enough that it gets its own section further down.

GenKitLab's Swagger Formatter converts an OpenAPI or Swagger file between YAML and JSON, sorts its paths and schemas, and puts every key back into specification order — entirely client-side. Nothing you paste is uploaded anywhere; it runs in your browser tab the same way the rest of GenKitLab's tools do.

Converting OpenAPI YAML to JSON sounds like a mechanical re-encoding, and for a flat document it would be. OpenAPI specs are rarely flat, though, and two YAML features specifically are where a naive converter breaks or silently produces the wrong JSON.

• Multi-line string block scalars (| and >). A long descriptionfield is exactly where a spec author reaches for YAML's block scalar syntax. | (literal style) preserves line breaks exactly as written; >(folded style) joins lines into a single space-separated string, collapsing the line breaks. A converter that doesn't distinguish these two — or that flattens both the same way — changes what the description field actually contains once it becomes a JSON string.
• Anchors and aliases (&anchor / *alias). Spec authors use an anchor to define a schema fragment once — a common error response shape, say — and an alias everywhere else to reuse it without retyping it. A correct converter resolves every alias back to the full anchored content before emitting JSON, since JSON has no equivalent reference mechanism at the YAML-parse layer. Silently dropping an alias, or emitting a bare string like *ErrorSchemainstead of the resolved object, produces JSON that's syntactically fine and semantically broken.

# YAML — hand-authored, with a block scalar and an alias
paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      description: |
        Returns the full user record, including
        profile fields and account status.
      responses:
        '404':
          $ref: '#/components/responses/NotFound'

---
{
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get a user by ID",
        "description": "Returns the full user record, including\nprofile fields and account status.\n",
        "responses": {
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  }
}

Note that the literal block scalar's line break became a real \n inside the JSON string, and the trailing newline the |style implies is preserved too — that's the detail a find-and-replace approach to converting yaml to json would get wrong.

A hand-edited OpenAPI file accumulates arbitrary key ordering the same way any long-lived, multi-author document does. One person adds an endpoint and types responses before parameters; six months later someone else edits a neighboring schema and types the fields in whatever order they were thinking about them. None of that is wrong — YAML and JSON objects are both unordered by spec — but it has a real cost in version control: two specs that are semantically identical can render as a large diff if keys merely got reordered, and a real content change can get buried in that same reordering noise, invisible to whoever's reviewing the pull request.

The fix is the exact same idea covered in GenKitLab's JSON Formatter guide for sorting object keys before diffing two JSON payloads — applied here to OpenAPI documents specifically. Instead of sorting alphabetically, though, a swagger beautifier worth using puts every key back into specification order — the order the OpenAPI spec itself documents fields in for a given object type (openapi, info, paths, components at the root;summary, operationId, parameters, requestBody, responses inside an operation, and so on). Alphabetical order would work for diff-stability too, but it scrambles a document a spec reader already knows how to scan; canonical order keeps it readable in the shape reviewers expect while still making diffs deterministic.

# as hand-edited over time — arbitrary order
get:
  tags:
    - users
  responses:
    '200':
      description: OK
  operationId: getUserById
  parameters:
    - name: id
      in: path
      required: true
  summary: Get a user by ID

---
# after formatting — canonical spec order
get:
  summary: Get a user by ID
  operationId: getUserById
  tags:
    - users
  parameters:
    - name: id
      in: path
      required: true
  responses:
    '200':
      description: OK

Run that through source control once and every future edit to this operation produces a diff that shows only the actual change — a new parameter, an updated description, a new response code — instead of a wall of moved lines that a reviewer has to read past to find the one line that matters.

Converting between YAML and JSON, sorting paths and schemas, and normalizing key order are all presentation-layer operations. None of them check whether the spec is actually correct — whether every $refresolves, whether required fields are present, whether the document satisfies the OpenAPI schema itself. A spec can be perfectly formatted and canonically ordered while still being invalid, and a formatter has no reason to catch that; it's a different question, answered by a different tool.

That's deliberately why formatting and validation are covered as two separate, complementary steps rather than one tool trying to do both. For the deeper question — is this OpenAPI document actually valid — see the OpenAPI Validator guide and GenKitLab's OpenAPI Validator. A practical order of operations: format first to convert to whichever encoding your tooling needs and get a clean, diffable file, then validate to confirm it's structurally sound before it ships to a codegen pipeline or a gateway that will trust it blindly.

• Before a pull request review. Formatting a spec to canonical key order before opening a PR means the diff a reviewer sees is exactly the endpoints or fields that changed — nothing more.
• Feeding a JSON-only tool. Some client SDK generators, gateway configs, and older OpenAPI-consuming tools expect JSON specifically; converting openapi to json once at the boundary is simpler than maintaining two hand-written copies of the same spec.
• Standardizing a spec inherited from another team. A file with mixed indentation, no consistent key order, and YAML aliases scattered throughout is hard to review as-is; a single formatting pass makes it legible before anyone touches its content.
• Keeping a spec readable during active development. Re-running a formatter after every batch of edits — to format swagger back into shape — keeps a spec from slowly drifting into the kind of inconsistent mess that makes the next diff harder to read than it needs to be.