⌘ K
swagger 2 → openapi 3 · paths · body params · refs · live

Upgrade Swagger 2 to OpenAPI 3

Convert legacy Swagger 2.0 documents (JSON or YAML) to the OpenAPI 3.0 shape. Host + basePath become servers, body / formData params become requestBody, and definitions move under components.schemas.

OpenAPI v2 → v3
Input
584 B
18 lines
Output
0 B
1 lines
Status
loading
parser…
Ratio
0.00×
out/in
input · swagger 2 json or yaml
output · openapi 3 json
Loading parser…
Quick Start

What the converter does

Swagger 2 keeps host/basePath/schemes; OpenAPI 3 uses a servers array. Body and formData parameters move into requestBody.content. response.schema becomes response.content[mime].schema. $refs under #/definitions/ are rewritten to #/components/schemas/.

  1. 01

    Paste the spec

    JSON works instantly; YAML triggers a lazy js-yaml load.

    Parsing runs through Prettier’s standalone bundle (or the language-specific equivalent) loaded lazily — no parser ships until the tool is opened.

    inputPrettierASTstandalonelazy
    in · sourcev2 · AST
    { "swagger": "2.0" }
    loaded · parsedAST · ready
  2. 02

    Hosts → servers

    host + basePath + schemes collapse into a servers entry per scheme.

    Indent width, tab style, and print-width re-format through a memoised pass — switching 2 → 4 spaces never re-parses, only re-prints.

    serversindentprint-widthmemoisedlive
    host · optionsserver · live
    https://api.example.com/v1
    options applied · livelive
  3. 03

    Body → requestBody

    Body and formData params consolidate into requestBody.content keyed by MIME.

    The formatter is deterministic and idempotent: running it twice produces byte-identical output, which keeps diffs and git noise to a minimum.

    bodyidempotentdeterministicdiff-cleanstable
    params · formattedcontent · ready
    requestBody.content["application/json"]
    formatted · liveidempotent
  4. 04

    Refs rewritten

    Anything pointing at #/definitions/ targets #/components/schemas/ instead.

    Download writes a Blob with the language-appropriate extension; copy uses navigator.clipboard.writeText so the output preserves all whitespace exactly.

    refsclipboardbloblanguage MIMEclient-side
    $ref · copiedcomponents · done
    #/components/schemas/User
    shipped · ready to shipsuccess
Pro tips

Formatting tips that keep diffs sane

Pick one config and pin it

Inconsistent formatting causes diff churn. Commit .prettierrc / .editorconfig and enforce in CI.

Format on save

Editor integration is faster feedback than a pre-commit hook. Use both for belt-and-braces.

Idempotency matters

Running the formatter twice should produce identical output. Test this on a representative file.

Match the language community

Default to community conventions: 2 spaces for JS/CSS, 4 for Python, tabs for Go. Fights over indent are a productivity tax.

Print-width drives wrapping

80, 100, and 120 are the common targets. Wider lines parse fast but review slower side-by-side.

Don’t mix formatters and linters

Prettier handles whitespace; ESLint handles correctness. Disable overlapping rules to avoid fight-club configs.

Related toolsOpenAPI to TypeScriptJSON to TypeScriptJSON to XMLHAR to cURLcURL to fetch()YAML to JSON
Use Cases

When to upgrade

Mass upgrades, tool compatibility, audits.

Mass upgrade

Migrate a fleet of legacy Swagger 2 docs to OpenAPI 3. Idempotent: running the formatter twice produces byte-identical output, which is the foundation of a clean CI gate. Pair with a pre-commit hook so PRs arrive already formatted, focusing review on logic.

idempotent

Tooling parity

Plug into modern generators that only accept OpenAPI 3. Pairs with EditorConfig + .prettierrc for end-to-end consistency. Whitespace-only changes vanish so reviewers see real diffs, and git blame stays honest about who wrote what.

CI-ready

PR diffs

Compare a freshly upgraded spec against the v2 source. Output respects your indent width, tab style, and print-width — settings carry over for repeat runs. Switching 2-space to 4-space costs nothing in CPU but standardises an entire codebase.

diff-clean

Spec authoring

Bootstrap a v3 doc from existing v2 definitions. Format-on-save is the fastest feedback loop; CI is the safety net. Together they make inconsistent indentation a thing of the past and free up review cycles for genuine concerns.

PR-friendly

Stale APIs

Modernise a frozen API while keeping the contract identical. Whitespace-only changes don't trigger downstream content-hash invalidations, so CDN cache keys and CI cache layers stay warm. Real changes get all the rebuild budget.

review-ready

Documentation

Re-host v2 docs in modern OpenAPI viewers. Pairs with linters (ESLint, Stylelint, pylint) that catch what formatting alone can't — bugs, unused imports, dead code. Each tool stays in its lane, and the codebase stays clean.

deterministic
FAQ

Frequently asked questions

Yes — js-yaml is lazy-loaded the first time you open the page. JSON works without the loader.
Common shapes (paths, body, formData, definitions, security) are upgraded. Edge cases may need swagger2openapi for full fidelity.
Yes — the same input always produces the same JSON. The conversion is pure.
Basic, apiKey and oauth2 are mapped to OpenAPI 3 securitySchemes. Custom schemes pass through as-is.
No. Parsing and conversion run locally in your browser.
Suggest a tool

Something missing?

Tell us what you need. We ship the top requests every two weeks.

Sent straight to the maintainers · no account needed
47 in queue·8 shipped this month
Request queued. Thanks!