Don't like ads? Go Ad-Free Today 

OpenAPI v2 to v3 Converter

DataDeveloper

ADVERTISEMENT · REMOVE?

INPUT

Auto Process

OUTPUT

Client Side

ADVERTISEMENT · REMOVE?

Guide

OpenAPI v2 to v3 Converter

Paste a Swagger 2.0 specification and get a valid OpenAPI 3.0.3 version back in either JSON or YAML. The converter applies the official structural mapping rules — moving definitions under components/schemas, collapsing host, basePath, and schemes into servers, splitting consumes and produces into per-operation content maps, and reshaping form parameters and security definitions — so your spec works with modern OpenAPI tooling.

How to Use

Paste your Swagger 2.0 spec into the input box. JSON and YAML are both accepted; the format is auto-detected.
Pick an output format: keep the input format, or force JSON or YAML.
Leave Patch missing required fields on to auto-fill mandatory v3 fields like info.title, info.version, and missing response descriptions when the v2 source omits them.
Read the conversion summary and any warnings shown above the output, then copy or download the resulting OpenAPI 3.0.3 spec.

Features

JSON and YAML in, JSON or YAML out — pick the format you prefer, or mirror the input.
Structural mapping — definitions → components/schemas, securityDefinitions → components/securitySchemes, parameters/responses are lifted under components, and every $ref pointer is rewritten to match.
Servers from host, basePath, schemes — combined into the v3 servers array, with HTTPS preferred when multiple schemes are listed.
Content negotiation — consumes and produces are translated into per-operation requestBody.content and responses[*].content maps.
Body and form parameters — in: body becomes a v3 requestBody, and in: formData fields are grouped into a multipart/form-data or application/x-www-form-urlencoded request body schema.
Security flow upgrade — OAuth2 flow values are remapped onto the v3 flows object (implicit, password, clientCredentials, authorizationCode).
Patch mode — when enabled, fills in missing required fields so the output passes a v3 validator instead of failing on minor source defects.
Conversion summary & warnings — counts of paths, schemas, and security schemes converted, plus warnings for anything that could not be mapped one-to-one.
Runs entirely in your browser — your spec never leaves the page.

 FAQ

What changed structurally between Swagger 2.0 and OpenAPI 3.0?

OpenAPI 3.0 reorganized reusable pieces under a single components object: definitions became components/schemas, parameters became components/parameters, responses became components/responses, and securityDefinitions became components/securitySchemes. The transport surface also changed: host, basePath, and schemes were merged into a servers array of full base URLs, while the implicit consumes and produces arrays were replaced with explicit content maps keyed by media type on each request body and response.
Why did request bodies need a new shape in OpenAPI 3.0?

In Swagger 2.0 a request body was just another parameter with in: body, and form fields were parameters with in: formData. That collapsed two different concerns (path/query/header parameters versus the request payload) into one list and made content-type negotiation awkward. OpenAPI 3.0 split them: parameters are only for path, query, header, and cookie; the payload moves to a top-level requestBody with a content map. This lets you describe a single endpoint that accepts application/json, multipart/form-data, and application/x-www-form-urlencoded with different schemas for each.
Are Swagger 2.0 and OpenAPI 3.0 wire-compatible?

No. They are description-format versions, not API protocol versions, so a converted spec does not change how your service responds at runtime — but tooling (generators, validators, mock servers, UI viewers) must understand the version you publish. OpenAPI 3.0 introduced features that have no v2 equivalent, including oneOf/anyOf/not, callbacks, links, and richer security flows. Going forward (v3 → v2) is therefore lossy in general, while going backward (v2 → v3) is largely mechanical because v2 is a strict subset of v3's expressiveness.
What does $ref resolution mean in this context?

A $ref is a JSON Reference pointer such as #/definitions/User. Conversion has to rewrite every pointer because the target path changes: #/definitions/User becomes #/components/schemas/User, #/parameters/AuthHeader becomes #/components/parameters/AuthHeader, and so on. The pointers themselves are not resolved (the document still references by location), but they must be rewritten in lock-step with the structural move so the resulting v3 spec stays internally consistent.