Swagger Editor
Home / Guide / Migrate 2.0 to 3.x

Migrating from Swagger 2.0 to OpenAPI 3 in Swagger Editor

What actually changes when you move an old Swagger 2.0 file to OpenAPI 3, and how to check the converted result.

7 min read · Updated October 2026

Side-by-side diff converting a Swagger 2.0 file to OpenAPI 3.0.3

Plenty of APIs are still described in Swagger 2.0, the format that later became OpenAPI 3. The newer versions are more expressive and better supported by modern tools, so migrating is usually worth it.

Swagger Editor reads both, which makes it a good place to check the before and after side by side.

The big structural changes

  • Version field. swagger: "2.0" becomes openapi: 3.0.3 or 3.1.0.
  • Servers. host, basePath and schemes merge into a servers list of full URLs.
  • Components. definitions, parameters, responses and securityDefinitions move under components, and every $ref path changes with them.
  • Request bodies. Body and form parameters are replaced by requestBody with a content map keyed by media type.
  • Responses. A response schema now sits inside content, so one response can offer JSON and XML separately. Global produces and consumes disappear.

Before and after

# Swagger 2.0
parameters:
  - in: body
    name: book
    schema:
      $ref: '#/definitions/Book'

# OpenAPI 3
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Book'

Automated conversion

Converters can do most of the mechanical work in seconds. Run one, open the output in the editor and treat it as a first draft.

Converters cannot know your intent, so watch for duplicated media types, lost examples and file uploads, which change shape in version 3.

3.0 or 3.1?

OpenAPI 3.1 aligns schemas with JSON Schema, replaces nullable: true with a type list such as [string, "null"], and adds webhooks. If your generators and gateways support 3.1, use it.

If any tool in your chain lags behind, 3.0.3 is the safe choice and moving up later is a small step.

A migration checklist

  1. Convert automatically and fix parser errors.
  2. Clear every validation error and warning in the editor.
  3. Compare operation counts and paths with the original.
  4. Regenerate one client and run its tests against a real server.
  5. Replace the old file in the repository in a single reviewed change.

Back to all guides or download Swagger Editor.