OpenAPI vs Swagger: what the names mean

Swagger originally named both an API description specification and its tooling ecosystem. The specification was donated to the OpenAPI Initiative and continued as the OpenAPI Specification. Swagger now usually refers to tools such as Swagger UI and Swagger Editor.

Swagger 2.0 is the older specification version. OpenAPI 3.0 and 3.1 are newer specification families with a different document structure and richer schema capabilities.

The top-level version field is the fastest signal. A Swagger 2.0 document uses `swagger: 2.0`. OpenAPI documents use an `openapi` field such as `3.0.3` or `3.1.0`.

// Swagger 2.0
{ "swagger": "2.0" }

// OpenAPI 3.1
{ "openapi": "3.1.0" }

OpenAPI 3 separates server definitions, reusable components and request bodies more clearly. It can describe several servers and content types without the Swagger 2.0 `host`, `basePath`, `schemes`, `consumes` and `produces` pattern.

OpenAPI 3.1 aligns its Schema Object more closely with modern JSON Schema, though tooling support can vary. Always check which version a parser actually implements.

• Swagger 2.0 stores reusable models under definitions.
• OpenAPI 3 uses components.schemas.
• OpenAPI 3 models request bodies separately from parameters.
• OpenAPI 3 response content maps media types to schemas and examples.

Keep a valid Swagger 2.0 definition if every consumer supports it and the contract is stable. Migrate when you need OpenAPI 3 capabilities, current ecosystem support or a cleaner representation of request bodies and content types.

Convert with a trusted tool, then review the result operation by operation. Automated conversion cannot confirm that old descriptions, examples and ambiguous schemas reflect actual behavior.

• Validate the converted document.
• Compare operation counts and identifiers.
• Review authentication schemes.
• Test generated requests against representative endpoints.

REST Test currently imports OpenAPI 3.x and Swagger 2.0 JSON documents. It normalizes supported operations and schemas into one internal model used by documentation, requests and code generation. YAML sources are supported through recognized .yaml/.yml URLs and GitHub; local file upload uses JSON.