OpenAPI vs Swagger

The API repos we run into keep showing the same setup. The spec starts with swagger: "2.0". Swagger UI renders it in the browser at /openapi. In the Confluence wiki the same file gets called a "Swagger file" on one page and an "OpenAPI spec" on the next. Sooner or later, someone in standup asks whether Swagger is still a reasonable choice in 2026.

We see this same setup in banks, industrial groups, and government agencies — across very different tech stacks and maturity levels. The confusion holds steady, and it comes down to one concrete cause.

A specification that used to be called Swagger was renamed to OpenAPI in 2015. The tools kept the old brand. Both names have been running side by side ever since, often in the same line of code.

Google "OpenAPI vs Swagger" today and most of the results are stuck halfway between a history lesson and an unfinished version comparison.

A short history from Swagger to the OpenAPI Specification

Tony Tam published the first version of the Swagger Specification in 2011, embedded in the Wordnik backend, which at the time had far more API traffic than most dictionary platforms. The spec was designed to be pragmatic and machine-readable. It spread quickly because it solved a problem everyone had and nobody was describing in a structured way.

Swagger 2.0 appeared in 2014 and became the de facto standard for API descriptions in short order. In November 2015, SmartBear handed the specification over to the Linux Foundation. That move gave rise to the OpenAPI Initiative, an open consortium that has stewarded the standard ever since. The specification itself was renamed to the OpenAPI Specification in 2016, while the Swagger brand stayed with SmartBear and shifted to refer to the family of tools.

The OpenAPI Initiative drew in companies that, taken together, are responsible for a large share of global API traffic. Google, Microsoft, IBM, Salesforce, PayPal, and Atlassian were among the founding and early premier members; Adobe, Intuit, and Oracle joined later. That broad backing is what kept the specification from depending on a single vendor and is why later iterations have stayed vendor-neutral.

The first major release under the new name was OpenAPI 3.0.0 in July 2017. It wasn’t a small update. It was a structural rework that corrected many of the earlier design decisions. Patch versions 3.0.1, 3.0.2, and 3.0.3 followed in the years after. February 2021 brought OpenAPI 3.1.0 with full JSON Schema compatibility, webhooks, and explicit support for null values. September 2025 added OpenAPI 3.2.0 with hierarchical tags, the QUERY method, and native support for streaming APIs. The version remains backward-compatible with 3.0 and 3.1.

Today both names continue to live in parallel. The specification is called OpenAPI, the tools are called Swagger, and both often turn up in the same line of code.

What’s what today. A map of the terms

In 2026, "Swagger" usually refers to a tool, and "OpenAPI" refers to the specification that used to be called Swagger. The overview below pins the terms down.

The dual vocabulary has two roots. SmartBear still owns the Swagger brand and actively develops tools under it, primarily Swagger UI and SwaggerHub. The OpenAPI Initiative carries the standard but has no tooling portfolio of its own. On top of that, there’s the simple matter of language habit. Anyone who’s been writing Swagger files for ten years rarely switches overnight to calling them OpenAPI files.

Swagger today is a brand. OpenAPI is an open standard. When somebody says "Swagger," they usually mean a tool from the SmartBear family or the old 2.0 spec format. "OpenAPI" refers to the format itself, the YAML or JSON file used to describe modern APIs.

What changed between the versions

Four version jumps matter in practice. Swagger 2.0 (2014) made the format the de facto standard. OpenAPI 3.0 (2017) cleaned it up structurally. OpenAPI 3.1 (2021) brought JSON Schema compatibility into line. OpenAPI 3.2 (2025) added hierarchical tags, the QUERY method, and streaming support. How much each jump affects you comes down to your existing tooling.

The structural rework from Swagger 2.0 to OpenAPI 3.0

The move from 2.0 to 3.0 changes the topology of the spec. Server definitions, schemas, security mechanisms, and request bodies were reorganized, not just renamed.

The important renames cluster around four spots. host, basePath, and schemes are now bundled into servers. definitions is now components.schemas. consumes and produces are no longer set globally but per operation, through requestBody and responses.content. securityDefinitions is now components.securitySchemes.

OpenAPI 3.1 adds JSON Schema, webhooks, and null types

3.1 is a smaller jump than the one before it, but consequential in the right places. Three changes matter.

• OpenAPI 3.1 is a fully conformant JSON Schema dialect. Up to that point, OpenAPI schemas had their own slightly diverging flavor. In 3.1, any JSON Schema construct can be used directly, including anyOf, oneOf, allOf, and $dynamicRef.
• Webhooks have a top-level construct of their own in 3.1. Until then, callbacks or pure event APIs had to be shoehorned into a callback construct or pulled out into a separate document. With 3.1, asynchronous triggers can be described cleanly inside the same document.
• null is explicit. In 3.0, you had to model it awkwardly via nullable: true. In 3.1, type: [string, "null"] is enough, which is what JSON Schema expects.

A minimal webhook in OpenAPI 3.1 looks like this.

Before 3.1, this use case had to be modeled either as a callback inside a regular operation or moved out into a separate AsyncAPI specification. Both routes still work. The webhook block is the direct alternative for pure event APIs.

Which version when

The question comes up in two situations. For new APIs, as a choice between OpenAPI 3.1 and 3.2. For existing systems, usually as a migration question from 2.0 or 3.0.

The realistic window for a 2.0 migration tends to be twelve to eighteen months in a mid-sized API landscape with twenty to fifty active APIs. The exact migration date matters less than the cutoff date after which new APIs are only created in 3.x. Without that cutoff, the existing footprint keeps quietly drifting along on 2.0, and the migration curve flattens out instead of declining.

Migrating from Swagger 2.0 to OpenAPI 3.x

A migration from Swagger 2.0 to OpenAPI 3.0 usually wraps up in a few days. The work rarely sits in the structural changes. It sits in the three or four sticking points that show up in nearly every codebase.

Five spots tend to change. The server definition moves out of host, basePath, and schemes into a servers block. Schemas move out of definitions into components.schemas. Request bodies are no longer modeled as parameters with in: body, but in requestBody with a content mapping. Responses get a content layer with media types instead of being defined globally through produces. Security mechanisms move out of securityDefinitions into components.securitySchemes.

A typical pain point shows up around file uploads. In Swagger 2.0, that’s a simple parameter. In OpenAPI 3.0, it’s a full requestBody.

Two tools have established themselves for the conversion itself. swagger2openapi as a CLI is the direct standard option. OpenAPI Generator can convert internally during SDK generation, which is useful when the spec primarily serves as generator input.

If you’re aiming straight for 3.1 or 3.2 in the same migration, you’ve already done the 3.0 step. The jump from 3.0 through 3.1 to 3.2 is much smaller than the jump from 2.0 to 3.0 and remains mostly schema work, since 3.1 and 3.2 are backward-compatible.

Is Swagger still relevant in 2026?

The question comes up mostly when teams re-evaluate spec tooling or when an existing 2.0 codebase heads into a larger modernization. Four aspects show up in this discussion over and over: Swagger UI, Swagger Codegen, the Swagger 2.0 format itself, and SwaggerHub as a commercial product.

Is Swagger UI still in use?

Yes. Swagger UI is effectively the default renderer for OpenAPI documents and runs on the order of hundreds of thousands of publicly accessible repositories and API endpoints. Spring REST, FastAPI, Express, ASP.NET Core, Flask, and Quarkus ship Swagger UI integration either out of the box or as a one-line setup. Competitors like Redoc and Scalar are gaining ground primarily in branding-driven developer portals where visual presentation is itself a product feature. In day-to-day technical work, where the goal is to render a spec quickly, they don’t actually replace Swagger UI.

Is Swagger Codegen still a reasonable choice?

Conditionally. Swagger Codegen has been largely superseded by OpenAPI Generator over the past few years. OpenAPI Generator emerged in 2018 as a community fork and has been maintained considerably more actively since, with over fifty language and framework templates and several releases per year. New projects usually start directly with OpenAPI Generator. Existing setups on Swagger Codegen continue to run, but the maintenance gap widens year over year, and new language targets show up almost exclusively in the Generator fork.

Should you still use Swagger 2.0?

For new APIs, no. Swagger 2.0 hasn’t been developed since 2014. For existing systems, there’s no acute migration pressure, but a medium-term migration to 3.x should be on the roadmap. New tools, new linters, and new generator templates test 3.x first; older 2.0 paths thin out continuously. If you’re keeping 2.0 on life support, document at minimum that it’s a legacy format and that no new specs go in it. Otherwise, two years from now you’ll have a 2.0 extension nobody wants to migrate.

What about SwaggerHub?

SwaggerHub is a commercial product from SmartBear, not an open standard. It’s one option among several API platforms. Other options include api-portal.io, Stoplight, Postman, and Bump.sh. The choice depends on factors like multi-tenant isolation, governance model, CI/CD integration, hosting model (SaaS or on-premises), and commercial model. SwaggerHub sits close to the Swagger ecosystem and pays off mainly when a team already works with Swagger UI and Swagger Editor. Other platforms cover more of the full API lifecycle, from spec management through linting to consumer onboarding.

How api-portal.io handles OpenAPI and Swagger

api-portal.io supports OpenAPI 3.x and Swagger 2.0 in parallel. On import, the platform detects the format automatically and converts Swagger 2.0 to OpenAPI 3.x as needed. The API Explorer renders both formats in a unified interface, and the API Linter checks both against the same style guide.

The API Explorer shows how both spec formats are presented.