How do I convert Swagger 2.0 to OpenAPI 3?

Paste your Swagger 2.0 (swagger: '2.0') spec. Specway migrates the structural changes: host+basePath+schemes become servers, body parameters become requestBody, definitions become components.schemas, securityDefinitions become components.securitySchemes, and consumes/produces become content media types per request body and response.

What's actually different between Swagger 2 and OpenAPI 3?

OpenAPI 3 reorganized the spec significantly: (1) servers replaces host/basePath/schemes. (2) requestBody replaces 'in: body' parameters. (3) components/schemas replaces definitions. (4) Each operation's content types are explicit per request body and response (no global consumes/produces). (5) Webhooks support, callbacks, links, and richer security schemes were added.

Should I migrate to OpenAPI 3?

Yes, if you can. OpenAPI 2.0 is in long-term maintenance — most modern tooling targets 3.0+ first, and 3.1 (which aligns fully with JSON Schema 2020-12) is the future. Migration is mostly mechanical and the converter handles the bulk of it. Validate the output and run tests.

Are all features migrated?

The structural conversions yes. Subtleties not covered: (1) the formData parameter type for multipart/form-data — converted but you may want to refine the schema. (2) custom security flows — basic/apiKey are migrated; OAuth2 flows need manual review. (3) extensions (x-*) are preserved unchanged but may not all map. Run the OpenAPI Validator on the output.

What's the difference between OpenAPI 3.0 and 3.1?

3.1 (released 2021) aligned with JSON Schema 2020-12. Key changes: webhook support, type can be an array (e.g. ['string', 'null']) instead of nullable, exclusiveMaximum is a number not a boolean. The converter outputs 3.0.3 because 3.1 has slightly less tooling support. To upgrade further, update the openapi version manually and run the validator.

Will my existing tooling break?

OpenAPI 3.0 is the current standard for almost all tooling — Swagger UI, Redoc, openapi-generator, postman, Spectral, and Specway all support it. Tools like swagger-codegen v2 are 2.0-only; switch to openapi-generator (codegen v3+) for OpenAPI 3 support.

How do I convert Swagger 2.0 to OpenAPI 3?

Paste your Swagger 2.0 (swagger: '2.0') spec. Specway migrates the structural changes: host+basePath+schemes become servers, body parameters become requestBody, definitions become components.schemas, securityDefinitions become components.securitySchemes, and consumes/produces become content media types per request body and response.

What's actually different between Swagger 2 and OpenAPI 3?

OpenAPI 3 reorganized the spec significantly: (1) servers replaces host/basePath/schemes. (2) requestBody replaces 'in: body' parameters. (3) components/schemas replaces definitions. (4) Each operation's content types are explicit per request body and response (no global consumes/produces). (5) Webhooks support, callbacks, links, and richer security schemes were added.

Should I migrate to OpenAPI 3?

Yes, if you can. OpenAPI 2.0 is in long-term maintenance — most modern tooling targets 3.0+ first, and 3.1 (which aligns fully with JSON Schema 2020-12) is the future. Migration is mostly mechanical and the converter handles the bulk of it. Validate the output and run tests.

Are all features migrated?

The structural conversions yes. Subtleties not covered: (1) the formData parameter type for multipart/form-data — converted but you may want to refine the schema. (2) custom security flows — basic/apiKey are migrated; OAuth2 flows need manual review. (3) extensions (x-*) are preserved unchanged but may not all map. Run the OpenAPI Validator on the output.

What's the difference between OpenAPI 3.0 and 3.1?

3.1 (released 2021) aligned with JSON Schema 2020-12. Key changes: webhook support, type can be an array (e.g. ['string', 'null']) instead of nullable, exclusiveMaximum is a number not a boolean. The converter outputs 3.0.3 because 3.1 has slightly less tooling support. To upgrade further, update the openapi version manually and run the validator.

Will my existing tooling break?

OpenAPI 3.0 is the current standard for almost all tooling — Swagger UI, Redoc, openapi-generator, postman, Spectral, and Specway all support it. Tools like swagger-codegen v2 are 2.0-only; switch to openapi-generator (codegen v3+) for OpenAPI 3 support.

Free Tool

Swagger 2 → OpenAPI 3 (2026)

Migrate your Swagger 2.0 spec to OpenAPI 3.0.3 in one click. Handles host/basePath → servers, body params → requestBody, definitions → components.schemas, and securityDefinitions → securitySchemes.

Swagger 2.0→OpenAPI 3.0

openapi: 3.0.3
info:
  title: Pet Store
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    get:
      operationId: listPets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
      parameters: []
    post:
      operationId: createPet
      parameters: []
      responses:
        '201':
          description: Created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

What changes between Swagger 2 and OpenAPI 3

host, basePath, schemes → servers: [{ url }]
parameters: [in: body] → requestBody
parameters: [in: formData] → requestBody with multipart/form-data
definitions → components.schemas
securityDefinitions → components.securitySchemes
$ref: #/definitions/X → $ref: #/components/schemas/X
consumes/produces become explicit per-operation content types
Non-body parameters get a schema wrapper instead of type at the top level

After migration

Run the OpenAPI Validator to confirm the output is structurally valid.
Run the OpenAPI Linter to catch new documentation-quality issues (operationIds, descriptions, error responses).
Manually review any OAuth2 security schemes — they need flow-by-flow updates.
Test SDK generation with your generator of choice (openapi-generator, openapi-typescript) — the v3 output is the modern target for all of them.
Update your CI to validate against OpenAPI 3 schemas going forward.

When the converter is enough vs not

For most Swagger 2.0 specs (CRUD APIs, common auth patterns), the converter produces a working OpenAPI 3 document in one click. For specs with heavy custom extensions, complex OAuth flows, or deep nested parameter shapes, manually review the output. The converter is the 95% — the last 5% is engineering.

Ship API docs that stay this clean

Specway turns your OpenAPI spec into a branded developer portal — auto-synced, searchable, with built-in playground and code samples in every language. Free tier available.

Related tools

OpenAPI Validator

Validate the migrated spec.

OpenAPI Linter

Check the migrated spec for quality issues.

OpenAPI Viewer

Browse the migrated spec.

OpenAPI → TypeScript

Generate TS types from the migrated spec.

Frequently asked questions