Swagger & OpenAPI Formatter
Convert an OpenAPI or Swagger file between YAML and JSON, sort its paths and schemas, and put every key back into specification order.
Input
JSON · 773 BFormatted
671 Bopenapi: 3.0.3
info:
title: Petstore
version: 1.0.0
paths:
/pets:
get:
operationId: listPets
responses:
'200':
description: Pets
/pets/{petId}:
get:
summary: Get one pet
operationId: getPet
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
'200':
description: A pet
default:
description: error
components:
schemas:
Error:
type: object
Pet:
type: object
properties:
id:
type: integer
name:
type: string
required:
- id
What changed
- Sorted 2 paths by route.
- Sorted 2 component entries by name.
- Reordered keys in 5 objects.
2 paths, 2 operations, 2 schemas and 1 parameters, unchanged. Only the ordering moved.
Formatting happens in your browser. Nothing is added, removed or renamed — the output parses back to a document that is deep-equal to the input, which the test suite asserts.
About the Swagger & OpenAPI Formatter
This Swagger formatter takes an OpenAPI or Swagger document and puts it in order: converts between YAML and JSON, sorts the maps whose order carries no meaning, and arranges the keys inside every object the way the specification lists them. It runs in your browser and never uploads the file.
The rule behind every decision here is which order is data and which order is accident. The order of `paths` is not data — nothing reads it, and sorting it is what makes two versions of a specification diffable, which is the main reason to run a formatter before committing one. The order of `components.schemas` is the same. But the order of a schema's `properties` is data in practice: it is the order documentation renders in and the order generated types declare their fields, so it is left exactly as written, always, no matter what the sort options say.
Key order inside an object is not data either, and putting keys into specification order makes a large document readable — `openapi`, `info`, `servers`, `paths`, `components` at the top level; `tags`, `summary`, `operationId`, `parameters`, `requestBody`, `responses` inside an operation. Vendor extensions and anything unrecognised keep their relative order and move to the end rather than being dropped.
Nothing is added, removed or renamed. The output parses back to a document that is deep-equal to the input, and the summary underneath confirms the path, operation, schema and parameter counts are unchanged.
- YAML to JSON and JSON to YAML, choosing the input format by content
- Keys reordered into the order the OpenAPI specification lists them
- Paths sorted by route and components sorted by name, each switchable
- Schema properties never sorted, because that order is author intent
- Responses ordered numerically with wildcards beside their range and `default` last
- A plain-English list of exactly what was reordered
- A structural check confirming nothing was added or lost
How to use it
- Paste your specification, or open the .yaml or .json file.
- Pick the output format. YAML is the usual choice for a file in a repository; JSON is what most tooling reads.
- Leave the sort options on for a document you are about to commit — that is what makes the next diff readable.
- Turn Sort paths off if your paths are grouped deliberately and you only want the key ordering fixed.
- Copy or download, and check the What changed panel to see precisely what moved.
Real-world use cases
API product & platform teams
Run a specification through the formatter before every merge so `git diff` on the spec file shows only the change that was actually made, not a few hundred lines of incidental reordering.
Backend developers
Convert a framework-exported spec between YAML and JSON to match whatever a downstream tool expects, without hand-editing key order or losing track of which schema properties were written in a deliberate sequence.
Frontend & client developers
Normalize a spec pulled from a teammate's branch before diffing it against the published version, so the comparison is about the API surface rather than about who ran a formatter and who didn't.
QA & API testers
Turn a minified or inconsistently indented spec into something readable before tracing through it by hand to write test cases against a specific operation.
DevOps & CI/CD engineers
Wire the same reordering rules into a pre-commit or CI check so a spec that was not run through the formatter fails fast, the same way an unformatted source file would.
Examples
Root keys in specification order
paths: {}
info:
version: 1.0.0
title: API
openapi: 3.0.3openapi: 3.0.3
info:
title: API
version: 1.0.0
paths: {}Both the root and the info object are reordered. Title before version is the order the specification documents.
Responses ordered properly
responses:
default: { description: error }
"5XX": { description: server error }
"200": { description: ok }responses: "200": ... "5XX": ... default: ...
A plain string sort puts 5XX before 200 and default in the middle. Wildcards sit beside their range and default goes last.
Properties left alone
User:
properties:
name: { type: string }
id: { type: string }User:
properties:
name: { type: string }
id: { type: string }Sorting components sorts the schema names, never the properties inside them. Property order is what your docs and generated types use.
Converting to JSON
openapi: 3.0.3
{
"openapi": "3.0.3"
}Same document, different encoding. The YAML reader refuses anything it cannot represent faithfully rather than guessing.
Common errors
| Message | Cause | Fix |
|---|---|---|
| mapping values are not allowed in this context | A YAML indentation mistake — most often a colon inside an unquoted string, such as a description containing a URL. | Quote the value. The parser reports the line, and a description with `https://` in it is the usual culprit. |
| The file contains more than one YAML document. | A stray `---` separator, often from concatenating two files. | An OpenAPI file is a single document. Remove the extra separators. |
| A tab was used for indentation | YAML forbids tabs in indentation entirely, and an editor set to insert tabs will produce a file no YAML parser accepts. | Convert the tabs to spaces. The parser gives you the line rather than a stack trace. |
| My diff is enormous after formatting | The first run reorders everything at once, so the first commit after adopting a formatter always touches the whole file. | Commit the reformat on its own, with no other change in it. Every diff after that is small, which is the point. |
| A version number turned into a different value | Unquoted YAML scalars are typed: 1.0 is a number, and 3.10 becomes 3.1. | Quote version strings. The YAML reader here warns where a value would change type on the round trip rather than doing it silently. |
| Vendor extensions moved to the bottom | Anything not in the specification's key list keeps its relative order and is placed after the known keys. | Intended. Nothing is dropped — turn off Specification key order if you need the original positions. |
Frequently asked questions
›Is my specification uploaded?
No. Parsing, reordering and serialising all happen in your browser, so a specification for an API you have not shipped yet stays on your machine. You can confirm it by formatting a file with your network disconnected.
›Could formatting change what my API means?
No. Nothing is added, removed or renamed — only the order of keys in objects changes, and object key order is not semantic in JSON or YAML. The tool shows you the path, operation, schema and parameter counts before and after so the claim is checkable, and the test suite asserts that the formatted document is deep-equal to the original.
›Why does it sort paths but never properties?
Because they are different kinds of order. Nothing reads the order of the paths map, so sorting it is pure gain: two versions of a specification become diffable. A schema's properties are different — that order is what documentation renders and what generated types declare their fields in, so it is a deliberate choice by whoever wrote it. Sorting it would be the tool overruling the author.
›Should I use YAML or JSON?
YAML for a file humans edit and review — it takes comments, and the diffs are smaller. JSON for anything a machine consumes, and for tooling that does not read YAML. Converting between them here is lossless in one direction only: YAML comments do not exist in JSON, so they are lost on that conversion. Keep YAML as the source of truth if your file has comments in it.
›Does it validate the document?
No — it formats. A document with a missing required field or a broken $ref will format perfectly well. The OpenAPI Validator on this site does the checking, and it shares this parser, so a file that formats here will parse there.
›Does it work on Swagger 2.0?
The formatting does. It is YAML or JSON either way, and the key ordering rules cover the fields 2.0 shares with 3.x while leaving anything unrecognised in place at the end. It does not convert 2.0 to 3.x — that is a rewrite of the structure, not a reordering.
›Why did sorting responses change nothing?
Probably because your response codes are all numeric. JavaScript objects already order integer-like keys numerically, ahead of every other key, whatever order the file wrote them in — so `500` then `200` is already `200` then `500` by the time any parser hands it over. The option only changes the outcome for keys that are not integers: `default` and the `2XX` wildcards.
›Will this fix errors in my specification?
No — it only reorders. A missing required field, a dangling $ref or an invalid enum value will format cleanly and remain exactly as broken as before. Run the OpenAPI Validator on this site first if you need to know whether the document is correct, then format it once it is.
Last updated