JSONToTable

Loading Swagger to OpenAPI Converter...

How to Convert Swagger 2.0 to OpenAPI 3.0 - Step by Step Guide

Automatically migrate Swagger 2.0 specs to modern OpenAPI 3.0.3 format with proper paths, security schemes, and components

Step 1

Paste Your Swagger 2.0 Specification

Paste your Swagger 2.0 spec in JSON or YAML format. The converter reads paths, definitions, and securityDefinitions and maps them to their OpenAPI 3.0 equivalents:

•
Paste directly: Copy your spec from Swagger Editor or your legacy API gateway
•
Upload a file: Load a swagger.json, swagger.yaml, or .yml file from disk
•
Try the sample: Click "Sample" to load a Bookstore API with endpoints, definitions, and an API key security scheme

Example: Swagger 2.0 Input

A book listing endpoint with a body parameter and definitions schemas:

swagger: "2.0"
host: api.example.com
basePath: /v1
paths:
  /books:
    post:
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Book'
definitions:
  Book:
    type: object
Step 2

Auto-Converted OpenAPI 3.0 Output

The converter produces a valid OpenAPI 3.0.3 spec. Key migrations performed automatically:

•
Body parameters → requestBody: Swagger in: body becomes a proper requestBody with content: application/json
•
definitions → components/schemas: All schema definitions are moved to the components/schemas object
•
securityDefinitions → components/securitySchemes: apiKey, basic, and oauth2 flows are mapped to their OpenAPI 3.0 equivalents
•
host + basePath → servers: Combined into a servers array URL entry

Example: Generated OpenAPI 3.0 Output

The same endpoint in OpenAPI 3.0 with a proper requestBody and components section:

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /books:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
Step 3

Validate and Use Your OpenAPI 3.0 Spec

Download the converted spec as YAML or JSON and validate it before deploying:

•
Validate the output: Run through our OpenAPI Validator to catch any remaining issues before use
•
Generate docs: Render with Swagger UI or Redocly for interactive API documentation
•
Generate client code: Use OpenAPI Generator or openapi-typescript with your new 3.0 spec to generate typed SDK clients

What is Swagger 2.0 to OpenAPI 3.0 Migration?

Swagger 2.0 (also called OAS 2) was the dominant API description format until 2017, when the OpenAPI Initiative released OpenAPI 3.0. The upgrade introduced a cleaner structure: body parameters became a first-class requestBody object, definitions moved to components/schemas, and multiple servers replaced the single host/basePath pattern.

The migration involves several structural changes: Swagger's in: body parameters are replaced with a requestBody with a content map keyed by media type. The securityDefinitions object maps to components/securitySchemes — with basic becoming http/basic, and OAuth2 flows renamed (accessCode → authorizationCode). $ref paths update from #/definitions/ to #/components/schemas/.

Modern tooling including Swagger UI 4+, Redocly, OpenAPI Generator, and Postman fully support OpenAPI 3.0, while Swagger 2.0 support is being phased out. Validate your converted spec with our OpenAPI Validator.

Common Use Cases

Legacy API Modernisation

Upgrade Swagger 2.0 specs from older codebases, API gateways, or third-party providers to OpenAPI 3.0 so you can use modern tooling. After converting, use our OpenAPI to TypeScript or OpenAPI to Go generators to produce typed client code.

Toolchain Compatibility

Many newer tools require OpenAPI 3.0 — Redocly CLI, Stoplight Studio, and the latest OpenAPI Generator templates all work best with 3.0 specs. Convert once and unlock the full modern ecosystem.

Frequently Asked Questions

What changes does the converter make automatically?

The converter handles: host + basePath → servers[]; body parameters → requestBody; formData → multipart/form-data requestBody; definitions → components/schemas; securityDefinitions → components/securitySchemes; OAuth2 flow renames; and all $ref path updates. Read more in the OpenAPI 3.0 overview.

Does the output need manual fixes after conversion?

For most straightforward Swagger 2.0 specs the output is valid OpenAPI 3.0. Complex cases — like polymorphism with discriminator, multi-value produces/consumes, or custom vendor extensions — may need manual review. Always validate the output with our OpenAPI Validator.

Can I convert a spec that is already OpenAPI 3.0?

The converter will show an error if you paste an OpenAPI 3.x spec — no conversion is needed. Only Swagger 2.0 (identified by the swagger: "2.0" field) is converted.

How are OAuth2 flows migrated?

Swagger 2.0 OAuth2 flow names are renamed to the OpenAPI 3.0 equivalents: accessCode → authorizationCode, application → clientCredentials. The authorizationUrl, tokenUrl, and scopes are preserved. See the OAuth2 authentication guide.

What tools accept OpenAPI 3.0?

Swagger UI, Redocly, Stoplight, Postman, OpenAPI Generator, openapi-typescript, and most modern API gateways (AWS, Kong, Apigee) all support OpenAPI 3.0.

Can I paste JSON or only YAML?

Both formats are supported. The converter auto-detects JSON (starts with {) and YAML. The output can be downloaded as either YAML or JSON using the format toggle buttons.

Is this Swagger to OpenAPI converter free?

Yes, completely free with no limits on spec size. No registration required. All conversion runs in your browser — your spec never leaves your device.

Related Tools

OpenAPI Validator

Validate OpenAPI 3.0 and Swagger 2.0 specifications online. Check required fields, paths, operations, schemas, and security schemes with instant error reporting.

JSON to OpenAPI

Generate OpenAPI/Swagger specifications from JSON examples. Infer data types and create complete API schemas automatically.

OpenAPI to Rust

Generate type-safe Rust API client code from OpenAPI/Swagger specifications with serde annotations.

OpenAPI to Go

Generate type-safe Go structs with JSON tags from OpenAPI 3.0 and Swagger 2.0 specifications.

OpenAPI to TypeScript

Convert OpenAPI 3.0 and Swagger 2.0 specifications to TypeScript interfaces and types. Auto-generate type-safe TypeScript from any OpenAPI schema.

OpenAPI to Markdown

Convert OpenAPI 3.0 and Swagger 2.0 specifications to readable Markdown API documentation. Generate endpoint tables, parameter docs, and schema references.