OpenAPI vs Swagger: What's the Difference?

"Swagger file" and "OpenAPI spec" get used to mean the same thing constantly, and for most everyday purposes that's close enough. But they're not actually the same name for the same thing anymore — one is a specification, one is a company's product line, and understanding how they split apart explains a lot of the version-numbering confusion you run into with real API documents.

The short answer

OpenAPI is the specification — the vendor-neutral, open standard that defines how to describe a REST API in JSON or YAML. Swagger is the original name that specification had before 2016, and today it's the brand name for a specific suite of tools (Swagger UI, Swagger Editor, SwaggerHub) built by SmartBear. The spec moved on and got renamed; the tools kept the old name.

A brief history

The Swagger specification was created in 2011 by Tony Tam at Wordnik, alongside a set of tools for generating interactive documentation from it — most notably Swagger UI, which is still the thing most people picture when they hear "Swagger." Through versions 1.0 to 2.0, Swagger was both the name of the spec and the name of the tooling built around it.

In 2015, SmartBear (which had acquired the Swagger API by then) donated the specification to the Linux Foundation, and the OpenAPI Initiative was formed as a vendor-neutral body to govern it going forward — with members including Google, Microsoft, IBM, and others alongside SmartBear. As part of that handoff, the specification itself was renamed from "Swagger" to the OpenAPI Specification (OAS), starting with what would have been "Swagger 3.0" but shipped instead as OpenAPI 3.0 in 2017.

SmartBear kept the Swagger name for its own tools — Swagger UI, Swagger Editor, Swagger Codegen, and the commercial SwaggerHub platform all still carry the Swagger brand today, and all of them read and write OpenAPI documents.

What "Swagger" means today

You'll see the word used in two legitimately different ways:

• Swagger 2.0 — the last version of the specification before the rename. It's a real, specific format, structurally different from OpenAPI 3.x, and still extremely common in codebases that haven't migrated.
• The Swagger tools — Swagger UI, Swagger Editor, and SwaggerHub, which today generate their documentation and editing experience from OpenAPI 3.x documents just as readily as from legacy 2.0 ones.

Calling a modern OpenAPI 3.x document a "Swagger file" is technically imprecise but universally understood — it's just leftover habit from when there was only one name for all of this.

What actually changed: Swagger 2.0 vs OpenAPI 3.x

Beyond the rename, the 3.0 release changed real structure, not just terminology:

• Reusable schemas moved from a top-level definitions object to components/schemas, alongside similarly reorganized reusable parameters, responses, and request bodies.
• Base URLs went from separate host, basePath, and schemes fields to a single servers array — which can list multiple environments and supports variable substitution in the URL itself.
• Request bodies became first-class. Swagger 2.0 described a JSON body as just another parameter with in: body. OpenAPI 3.x gives it its own requestBody object, keyed by content type — which also means a single operation can properly describe accepting JSON or form data with different schemas for each.
• consumes/produces disappeared in favor of declaring content types directly wherever a body is described, on both requests and responses.
• OpenAPI 3.1 went a step further and fully aligned with JSON Schema 2020-12 — notably replacing the non-standard nullable: true flag with proper type arrays like type: [string, null], and adding top-level webhooks support.

Which one should you write today

OpenAPI 3.x — specifically 3.0.x for the broadest tool compatibility, or 3.1.x if you specifically need its closer JSON Schema alignment. Swagger 2.0 is legacy at this point: stable, still widely deployed, and well worth supporting if you're working with an existing document, but not what you'd choose for something new.

Try it yourself

Every OpenAPI tool on this site reads both formats, so you don't need to convert anything first. Browse either format with the OpenAPI Viewer, check a document for structural mistakes with the OpenAPI Validator, or compare two versions — including a Swagger 2.0-to-OpenAPI-3.x migration — with OpenAPI Diff. All three run entirely in your browser; nothing you paste is ever uploaded.