Bloom*

Reference

Swagger vs OpenAPI: what changed, what didn't, and what to use in 2026

· 3 min read · Bloom

  • openapi
  • swagger
  • api-design

A surprising amount of confusion in API tooling comes from one rename. This is the short version of what Swagger and OpenAPI actually are in 2026, and what you should standardize on if you are starting fresh or moving off something older.

The one-line version

  • Swagger is the historical brand that produced the original spec (Swagger Spec 1.0, 1.2, 2.0). The brand is now owned by SmartBear and refers to a suite of tools (Swagger UI, Swagger Editor, Swagger Codegen) — not the spec.
  • OpenAPI is the spec itself, now versions 3.0.x and 3.1.x, governed by the OpenAPI Initiative under the Linux Foundation.

If you hear "Swagger file," people usually mean an OpenAPI document (often the older 2.0 form). The spec has had a real name change since 2017; the colloquial name lagged.

The version timeline

Year Spec name What changed
2011 Swagger Spec 1.0 First public release.
2014 Swagger Spec 2.0 The version most tools were built against. JSON / YAML.
2017 OpenAPI 3.0.0 Renamed. Cleaner schema model (components), oneOf/anyOf, link objects, callbacks. Not backwards-compatible with 2.0.
2021 OpenAPI 3.1.0 Aligned with JSON Schema 2020-12. Webhooks first-class. null is a real type. Minor structural cleanups.
2024 OpenAPI 3.1.x Stable, broad tool support.

OpenAPI 3.0 ↔ 3.1 is mostly forward-compatible at the document level — the big shift is the JSON Schema alignment in 3.1, which makes downstream codegen friendlier.

What to use today

For a new project, start with OpenAPI 3.1. Tool support is broad enough that the few rough edges (some older SDK generators still target 3.0 by default) are worth living with. The JSON Schema alignment alone is worth the upgrade: it removes a class of weird inference bugs in generated SDKs.

For an existing project on Swagger 2.0 / OpenAPI 2.0: the right time to upgrade is whenever you are already touching the spec for a real reason — adding endpoints, redesigning auth, changing version strategies. Don't upgrade purely for the sake of upgrading; do it when the next thing you ship benefits from oneOf / discriminator / cleaner security schemes / link objects.

For an existing project on OpenAPI 3.0: the upgrade to 3.1 is mostly painless, and the JSON Schema alignment helps any team that generates SDKs.

What changes if you upgrade 2.0 → 3.0

The structural shifts that matter day-to-day:

  • definitions: → components.schemas:. Everything reusable lives under components.
  • parameters: { in: body } → requestBody:. Bodies are no longer parameters; they have their own keyword.
  • host: + basePath: + schemes: → servers:. A list of base URLs with templated variables.
  • security: [{ apiKey: [] }] → securitySchemes: plus per-operation security:. Auth definitions live under components.
  • oneOf / anyOf / allOf are first-class. Polymorphism finally has a clean representation.

Stainless's open-source upgrader (stainless / docs / openapi / upgrade) handles the mechanical pieces. Bloom reads either form, but the migration report flags 2.0-specific oddities so you know what to clean up.

What changes if you upgrade 3.0 → 3.1

The shifts that matter:

  • JSON Schema 2020-12. type: ["string", "null"] is now valid (instead of nullable: true).
  • Webhooks at the top level. No more shoehorning into callbacks:.
  • exclusiveMinimum / exclusiveMaximum are booleans → numbers. Matches JSON Schema.
  • example: / examples: rules align with JSON Schema.

Most teams find the upgrade is a few hours of work, mostly running a codemod and then human-reviewing the diff.

How Bloom handles each version

  • 2.0 — Bloom reads, then suggests an upgrade to 3.1 as part of the report. The migration scanner shows which fields move and which stay.
  • 3.0 — Bloom reads and generates directly. Suggested upgrade to 3.1 if your team is interested.
  • 3.1 — First-class. The generated SDKs use the JSON Schema alignment for accurate Optional[X] / X | null typing.

What to do this week

  • Check openapi: (or swagger:) at the top of your spec. If it's 2.0, plan a 3.1 upgrade for the next major cycle.
  • If you are choosing tools, prefer ones that explicitly support 3.1. Older 2.0-only tools mean your spec stays trapped at 2.0.
  • If you are evaluating SDK generators, Bloom's OpenAPI SDK Generator reads 3.0 and 3.1 and emits TypeScript and Python.

The naming is unfortunate. The work is straightforward.