Chapter 01 of 10
OpenAPI vs Swagger
Where the two names come from, what changed when Swagger 2.0 became OpenAPI 3.0, which tools still carry the Swagger name, and which file your tooling actually expects.
Two names sit on the same subject, and people use both for both things. The confusion is historical rather than technical, so a short history settles it.
One specification, two names
The format started as Swagger, a project first released in August 2011. Version 2.0 followed in September 2014 and became the format most tooling supported.
At the end of 2015 the specification was donated to the OpenAPI Initiative, which the revision history in the specification itself records as the entry for 31 December 2015. The next major release came out on 26 July 2017 under the new name, as OpenAPI 3.0.0, and every version since has carried it.
So the specification is called OpenAPI, and it has been for about a decade. The name Swagger stayed with the tools.
What Swagger means today
SmartBear owns the Swagger trademark and ships a family of tools under it. Swagger UI renders an OpenAPI document as browsable reference pages, Swagger Editor edits one, Swagger Codegen generates client and server code from one, and SwaggerHub is the hosted product around all of that.
None of those names describe a file format. When somebody sends you a Swagger file, they mean an OpenAPI document, and the only thing worth asking is which version.
Telling the versions apart
The root of the document says which format you are holding, and it takes one line to check.
swagger: "2.0" # the format formerly known as Swagger 2.0openapi: 3.1.0 # OpenAPI 3, the current lineThe difference matters because the two are not shaped alike. Version 2.0 has definitions, parameters with a body location and a single produces list for the whole document. Version 3 replaced all of that with components, a separate requestBody object and a content map keyed by media type. A parser built for one will not read the other.
What changed between 2.0 and 3.0
Four changes account for most of the difference, and each of them removes a workaround the older format needed.
Request bodies became their own thing. In 2.0 a body was a parameter whose location was body, which meant a body could not have several media types and could not be reused cleanly. Version 3 gives it a requestBody field with a content map.
Content types moved next to the content. The global consumes and produces lists disappeared, so each request body and each response declares its own media types and a schema for each one.
Reusable pieces got one home. Instead of definitions, parameters and responses as separate top-level maps, everything reusable moved under components.
Servers replaced the host triple. The single host, basePath and schemes fields became a servers array with full URLs and variables, which is what lets one document describe several environments.
Which files your tooling expects
Most current tooling reads OpenAPI 3.0 and 3.1, a good deal of it still reads 2.0, and a converter sits in front of anything that does not. The practical rule is that the file you keep should be the newest version your generators handle, because everything downstream inherits its limitations.
Converting upward is mechanical and well supported. What conversion cannot do is add the descriptions, examples and error responses the old document never carried, and those are the parts that decide whether the generated output is useful. The version chapter covers the upgrade from 3.0 onward in detail.
In Routebase
Routebase authors specifications as OpenAPI 3.0, 3.1 or 3.2, and new specifications default to 3.2. An existing file goes in through the import wizard, which detects the version, validates the document and shows you what it found before anything is created.
Whatever wrote the file originally, the workspace holds it as a structured specification from that point on, and every frozen version leaves again as standard YAML or JSON. The Import and Export guide covers both directions, and the Swagger comparison covers the tooling question rather than the format one.
Frequently asked questions
What is the difference between OpenAPI and Swagger?
OpenAPI is the specification and Swagger is a set of tools named after it. The specification was called Swagger up to version 2.0, which was donated to the OpenAPI Initiative on 31 December 2015 and continued under the new name as OpenAPI 3.0.0 in July 2017. So a file written today is an OpenAPI document, while Swagger UI and Swagger Editor are tools that read one.
Is Swagger 2.0 the same as OpenAPI 2.0?
Yes, those are two names for the same document format. People write OpenAPI 2.0 to make the lineage clear. The OpenAPI Initiative's own revision history lists version 2.0 twice, once as the Swagger release in 2014 and once as the donation at the end of 2015. Tooling usually recognises it by the root field, which reads swagger rather than openapi.
Should I upgrade a Swagger 2.0 file to OpenAPI 3?
Usually yes, because the newer specification separates request bodies from parameters, supports several content types per response and has a components section that actually holds everything reusable. Converters handle most of the work. What they cannot do is invent the descriptions and examples the older file never had, so budget for reading the result rather than for running a command.
What is the swagger field at the top of a file?
It is the marker of a version 2.0 document. A 2.0 file starts with swagger followed by the version string, while a version 3 file starts with openapi followed by something like 3.1.0. Checking that one line is the fastest way to tell which format you have been handed before you feed it to anything.
Last reviewed by The Routebase Team.