OpenAPI vs Swagger: what's the difference between the two specs?

Swagger 2.0 and OpenAPI 2.0 are actually the same API description specification. API tooling company SmartBear transferred Swagger 2.0 to the OpenAPI Initiative in 2015, leading subsequent versions of the Swagger spec to adopt the OpenAPI name, while Swagger remained SmartBear's brand for tools such as Swagger UI and Swagger Editor.

The latest versions of the spec are OpenAPI 3.1 and 3.2. The OpenAPI 3.1 spec currently has the widest support base and is recommended for new projects. In this article, we compare 2.0 and 3.x, explain the differences between versions, and clarify how Swagger tooling works with modern OpenAPI documents. For a practical walkthrough of turning a spec into published docs, see how to write API documentation.

Mintlify makes it easy to create beautiful docs from an OpenAPI spec, generating endpoint reference pages and an interactive API playground that stay aligned as the spec evolves.

How Swagger became OpenAPI

Swagger originally named both the API description format and its supporting tools. In 2015, SmartBear donated Swagger 2.0 to the newly formed OpenAPI Initiative, an open governance project under the Linux Foundation. The donated format became OpenAPI 2.0, which is semantically identical to Swagger 2.0, and subsequent specification releases adopted the OpenAPI name.

While once synonymous, the two terms now have distinct meanings:

• OpenAPI Specification: A vendor-neutral, language-agnostic standard for describing HTTP APIs, maintained by the OpenAPI Initiative.
• Swagger: SmartBear's API tool suite, including Swagger UI, Swagger Editor, and Swagger Codegen. These tools work with modern OpenAPI documents as well as the older 2.0 format.

In legacy codebases, "Swagger" often refers to a document that begins with swagger: "2.0".

What is the OpenAPI specification?

The OpenAPI Specification defines a language-agnostic structure for describing HTTP APIs in JSON or YAML. An OpenAPI spec can record server URLs, paths, operations, parameters, request bodies, response schemas, authentication requirements, and reusable components.

Its structured format allows documentation generators, validators, mock servers, contract-testing tools, and code generators to read the same API definition. Developers can also inspect the spec directly to understand the available operations and expected data formats.

An OpenAPI spec becomes a reliable source for generated documentation and tooling when it is maintained alongside the implementation. Reviewing both within the same release process reduces inconsistencies between the API behavior, reference pages, SDKs, and tests derived from the spec. For the fundamentals of building that documentation, see our API documentation guide.

What does Swagger mean today?

Swagger is SmartBear's brand for tools that create, validate, visualize, and generate code from API definitions. The main open-source tools serve different parts of the API lifecycle:

• Swagger Editor: Authors and validates OpenAPI definitions while rendering the resulting API documentation. OpenAPI 3.1 support is available through Swagger Editor Next.
• Swagger UI: Converts an OpenAPI definition into interactive documentation that lets developers inspect operations and send API requests.
• Swagger Codegen: Generates client SDKs, server stubs, and API documentation from an OpenAPI definition.

A product carrying the Swagger name may support several OpenAPI versions, including the legacy 2.0 format. Version coverage varies across tools and releases.

Swagger 2.0 vs. OpenAPI 3.x

Swagger 2.0 and OpenAPI 2.0 describe the same format, so the technical comparison is between the 2.0 structure and the OpenAPI 3.x release line. Features in the 3.x column were introduced across versions 3.0, 3.1, and 3.2.

Area	Swagger 2.0 / OpenAPI 2.0	OpenAPI 3.x
Version field	swagger: "2.0"	openapi: 3.x
Server URLs	host, basePath, and schemes; one host per spec	servers array with multiple URLs and templated variables
Reusable objects	Separate definitions, parameters, responses, and security sections	Reusable objects grouped under components
Request bodies	in: body and formData parameters	Dedicated requestBody object
Media types	consumes and produces at the root or operation level	content maps within request bodies and responses
Schema composition	Supports allOf; excludes oneOf, anyOf, and not	Supports allOf, oneOf, anyOf, and not
Outbound requests	No callbacks or webhooks	Callbacks in 3.0 and top-level webhooks in 3.1
JSON Schema	Subset of JSON Schema Draft 4 with Swagger extensions	OpenAPI schema model in 3.0; JSON Schema Draft 2020-12 compatibility in 3.1
Release line	Maintained as the 2.0 compatibility format	Actively developed, with 3.2 as the latest release

Server definitions

Swagger 2.0 builds the base URL from three top-level fields. A spec can list several transfer protocols, but it defines one host and base path.

host: petstore.swagger.io
basePath: /v2
schemes:
  - https

OpenAPI 3.x replaces those fields with a servers array. Each entry contains a complete URL, and the spec can define separate production, sandbox, and regional servers. Server variables can also represent values such as environments, regions, or versions.

servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)

Reusable components

Swagger 2.0 distributes reusable definitions across several top-level sections. OpenAPI 3.0 introduced the components object, which groups schemas, parameters, responses, examples, request bodies, headers, security schemes, links, and callbacks.

Objects stored under components take effect only when referenced elsewhere in the spec. A reusable schema, such as Pet, can be referenced via $ref: "#/components/schemas/Pet" across multiple operations.

Request bodies and media types

Swagger 2.0 represents a request body as a parameter with in: body, while form fields use in: formData. Supported media types appear in consumes and produces arrays at the root or operation level.

OpenAPI 3.0 introduced a dedicated requestBody object. Its content map associates each media type with its own schema and examples. Responses use the same structure, allowing JSON, XML, form data, and other representations to be described independently for each operation.

Schema composition, callbacks, and webhooks

Swagger 2.0 supports schema composition through allOf. OpenAPI 3.0 added oneOf, anyOf, and not, allowing a schema to describe alternative or excluded data shapes with standard composition keywords.

OpenAPI 3.0 also introduced callbacks for outbound requests associated with a specific operation and links for connecting response values to other operations. Version 3.1 added top-level webhooks for event-driven requests that do not depend on a preceding API call. An OpenAPI 3.1 spec can include paths, webhooks, components, or any combination of the three.

JSON Schema compatibility in OpenAPI 3.1

Swagger 2.0 uses a defined subset of JSON Schema Draft 4, while OpenAPI 3.0 uses an OpenAPI-specific schema model. OpenAPI 3.1 aligns its Schema Object with JSON Schema Draft 2020-12.

The alignment replaces the OpenAPI-specific nullable keyword with type arrays such as type: ["string", "null"], supports $schema declarations, and enables standard JSON Schema keywords such as if, then, and else. Schema definitions can therefore move between OpenAPI and JSON Schema tooling with fewer format-specific adjustments.

Additions in OpenAPI 3.2

OpenAPI 3.2 extends the 3.x structure with richer tag metadata, explicit support for streaming and server-sent events, the QUERY method, and additionalOperations for HTTP methods outside the predefined set. Adoption still depends on whether each documentation, validation, and code-generation tool supports the new version.

Is Swagger deprecated?

Swagger 2.0 format: The OpenAPI Initiative still publishes the format as OpenAPI 2.0, and many tools continue to support it for existing APIs. New specification features are developed in the 3.x release line, making 2.0 a legacy format for compatibility-driven use cases.

Swagger tools: Swagger UI, Swagger Editor, Swagger Codegen, and related SmartBear products remain active. They work with OpenAPI definitions, although support for specific versions varies by tool and release.

Which OpenAPI version should you use?

Choose the version with the broadest support across your entire API toolchain. Compatibility must extend across documentation generators, validators, API gateways, mock servers, contract-testing tools, and SDK generators.

OpenAPI 3.1 (recommended): The best default for a new API. It has the widest tooling support, provides full compatibility with JSON Schema Draft 2020-12, supports modern OpenAPI structures such as top-level webhooks, and is the version Mintlify generates documentation from.

OpenAPI 3.2: The newest published version, fully backward compatible with 3.1. Adopt it once every required tool accepts 3.2 and your API benefits from features such as streaming semantics, richer tags, or additional HTTP operations.

OpenAPI 3.0: Existing toolchains may still require 3.0. Moving to 3.1 requires several Schema Object changes, including updates to nullable types, numeric constraints, examples, and file descriptions, so validate the migrated spec across every downstream tool.

Swagger 2.0 / OpenAPI 2.0: Existing 2.0 specs can be converted to OpenAPI 3.0 with tools such as swagger2openapi. Review and validate the converted output before moving from 3.0 to 3.1 or 3.2.

For a new API, default to OpenAPI 3.1 for the widest compatibility, and move to 3.2 only once your toolchain fully supports it. Reserve 3.0 and 2.0 for compatibility requirements in existing environments.

Generate API documentation from OpenAPI with Mintlify

Mintlify generates API reference pages from OpenAPI 3.0 and 3.1 specifications in JSON or YAML. Add the spec to your documentation repository or reference a hosted URL, then connect it to the navigation in docs.json. Mintlify creates a page for each endpoint, organizes the pages in the navigation, and presents the parameters, schemas, responses, authentication details, and code samples defined in the spec. Its API playground also lets developers enter credentials, send requests, and inspect responses within the documentation.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "openapi": "openapi.json"
    }
  ]
}

Updating the referenced spec refreshes the relevant endpoint content and playground, reducing manual maintenance after API changes. For examples of well-structured API references, see 5 API documentation examples worth studying. Perplexity uses Mintlify for its developer documentation, including an interactive playground for its chat completions endpoint.

Start generating your API documentation with Mintlify for free →

Frequently Asked Questions

Is Swagger the same as OpenAPI?

Swagger 2.0 API spec was converted to OpenAPI 2.0. These specs are identical, but the names have quite different meanings today. Swagger 2.0 refers to the format that preceded OpenAPI 3.0, while Swagger also remains the name of SmartBear's OpenAPI tooling.

What is the difference between Swagger 2.0 and OpenAPI 3.0?

OpenAPI 3.0 introduced a more flexible structure for server URLs, reusable components, request bodies, and media types. It also expanded schema composition and added support for callbacks and links.

Do Swagger tools work with OpenAPI 3.x?

Yes, modern Swagger tools work with OpenAPI 3.x, although support differs by product and release. For example, OpenAPI 3.1 requires Swagger Editor Next because the legacy Editor 4 does not support it.

Which OpenAPI version should I use for a new API?

Default to OpenAPI 3.1. It has the widest tooling support and is the version Mintlify generates documentation from (Mintlify currently supports OpenAPI 3.0 and 3.1). Move to 3.2 only once your whole toolchain supports it, and choose 3.0 when a required tool has not adopted 3.1.