Swagger 2 to OpenAPI 3

What changes during Swagger 2 migration

Swagger 2 stores the server location across schemes, host, and basePath. OpenAPI 3 uses a servers array, so the converter combines the first declared scheme with the host and base path. Reusable definitions move to components.schemas, reusable responses move to components.responses, and ordinary reusable parameters move to components.parameters. Local references are rewritten to those new locations.

Swagger body parameters become an OpenAPI requestBody. The applicable consumes media type becomes a content key and the original body schema is preserved. Common formData parameters become an object schema under URL-encoded or multipart content; file parameters become strings with binary format. Operation responses move their schema under media-type content based on produces.

Security schemes and OAuth flows

API-key schemes retain their name and header or query location. Swagger’s basic authentication becomes an OpenAPI HTTP security scheme with the basic scheme. OAuth 2 flows are mapped from Swagger names: application becomes client credentials, accessCode becomes authorization code, and implicit and password retain their corresponding OpenAPI flow. Authorization URLs, token URLs, and scopes are copied when present.

Conversion changes document shape, not security behavior. Confirm that the resulting scheme names still match every security requirement and that OAuth endpoints use the correct environment. Do not assume a syntactically converted contract proves that authentication works.

Validate the migrated contract

The output is formatted JSON so the structural changes are easy to review in a diff. Run the OpenAPI Validator and OpenAPI Linter after conversion. Compare the exposed paths and operations with OpenAPI Viewer, then run the contract through the same generator, documentation, gateway, and client tooling used in production.

A safe migration keeps the Swagger source and converted OpenAPI file together until consumers accept the new artifact. Test request serialization, multipart uploads, response media types, authorization, and generated SDKs. Commit the converted file as a reviewed change rather than overwriting the only known-good contract immediately.

Scope and manual review limits

This converter handles common Swagger 2 objects without downloading external references. It does not resolve remote $ref files, infer missing hosts, merge several schemes into server variants, preserve vendor-specific generator behavior, or guarantee that every unsupported extension has an OpenAPI equivalent. Reusable body parameters are resolved when referenced by an operation; ordinary reusable parameters may be inlined during path conversion.

Collection formatting, complex examples, unusual headers, callbacks, links, discriminators, and advanced schema differences may require manual migration. The lightweight YAML reader supports ordinary mappings, lists, and scalar values but not every YAML feature. Parsing and conversion happen in the browser, and declared API servers are never contacted. After the migration is stable, use OpenAPI Diff or API Guard to review future contract changes.