OpenAPI vs Swagger: What's the Difference?

If you've worked with APIs for any length of time, you've encountered both "Swagger" and "OpenAPI." They're used interchangeably in blog posts, documentation, and tool names. But they're not the same thing — and understanding the distinction matters when you're choosing tools, writing specs, or building integrations.

The Short Answer

OpenAPI is the specification. Swagger is a set of tools built around it.

Think of it like this: HTML is the specification, and Chrome is a tool that renders it. OpenAPI defines how to describe an API in a standard format. Swagger provides tools to create, view, and generate code from that description.

The History

2010–2015: Swagger the Spec

Swagger started in 2010 as a specification for describing RESTful APIs, created by Tony Tam at Wordnik. The original goal was simple: define an API in a machine-readable format so tools could generate documentation and client SDKs automatically.

Swagger 1.0 shipped in 2011. Swagger 2.0 arrived in 2014 with significantly better support for complex types, file uploads, and authentication schemes. By 2015, Swagger 2.0 was the de facto standard for API documentation.

2015: The Handoff to OpenAPI

In 2015, SmartBear Software (which owned Swagger) donated the specification to the newly formed OpenAPI Initiative under the Linux Foundation. The spec was renamed to OpenAPI Specification (OAS).

The Swagger name was retained for SmartBear's tooling: Swagger Editor, Swagger UI, Swagger Codegen. The specification itself became OpenAPI.

2017–Present: OpenAPI 3.x

OpenAPI 3.0 launched in 2017 with major improvements:

• components section consolidating reusable schemas, parameters, and responses
• Better support for oneOf, anyOf, and not (JSON Schema keywords)
• Link objects for describing relationships between operations
• Callback support for webhooks
• Improved security scheme definitions

OpenAPI 3.1 (2021) went further by achieving full alignment with JSON Schema Draft 2020-12, eliminating the long-standing "OpenAPI JSON Schema dialect" confusion.

OpenAPI 3.2 is expected to formalize webhook descriptions and improve multi-server support.

Current State: Who Uses What

Name	Type	Current Version
OpenAPI Specification	Spec (the standard)	3.1
Swagger UI	Tool (renders specs)	5.x
Swagger Editor	Tool (writes specs)	4.x (now Stoplight Studio)
Swagger Codegen	Tool (generates clients)	3.x
SwaggerHub	Platform (hosting + collaboration)	SaaS

The naming confusion persists because many tools still use "Swagger" in their names even though they work with OpenAPI specs. swagger-ui renders OpenAPI 3.x files just fine.

Practical Differences for Developers

Writing Specs

If you're writing a new spec, use OpenAPI 3.1 (YAML or JSON). It's the current standard, has the best tooling support, and aligns with JSON Schema.

# OpenAPI 3.1 example
openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Swagger 2.0 is still widely used but increasingly considered legacy. If you're starting fresh, there's no reason to use 2.0.

Key Syntax Differences

If you're migrating from Swagger 2.0 to OpenAPI 3.x, watch for these changes:

• host, basePath, schemes → replaced by servers
• definitions → moved to components/schemas
• parameters inline → moved to components/parameters
• consumes/produces → replaced by content on each operation
• type: file → replaced by format: binary

Tooling Compatibility

Most modern tools support both formats, but with caveats:

• Swagger UI 5.x — renders both Swagger 2.0 and OpenAPI 3.x
• Postman — imports both, exports OpenAPI 3.x
• Stoplight — native OpenAPI 3.x, imports Swagger 2.0
• Redoc — best with OpenAPI 3.x, supports 2.0
• openapi-generator — supports both, but 3.x features get better support

Migrating from Swagger 2.0 to OpenAPI 3.x

Option 1: Automated Conversion

# Using api-spec-converter
npm install -g api-spec-converter
api-spec-converter --from=swagger_2 --to=openapi_3 \
  --syntax=yaml input.yaml > output.yaml

This handles most cases but may need manual fixes for complex allOf compositions or custom extensions.

Option 2: Rewrite in OpenAPI 3.x

For smaller specs, rewriting is often faster than debugging converter output. Use the OpenAPI 3.x structure and copy-paste your endpoint definitions.

Option 3: Use a Visual Editor

Tools like Stoplight Studio let you import Swagger 2.0 and export OpenAPI 3.x with a visual diff. Good for teams that prefer GUI over YAML editing.

Why This Matters for API Monitoring

When you're monitoring third-party APIs for breaking changes, the spec format matters:

• OpenAPI 3.x specs provide richer type information, better schema composition, and more accurate validation
• Swagger 2.0 specs lack some features (webhooks, callbacks, full JSON Schema support) but are still widely published
• Some APIs publish both — always prefer the 3.x version
• Some APIs publish neither — you'll need to reverse-engineer specs from documentation or response samples

SchemaWatch supports both OpenAPI 3.x and Swagger 2.0 specs. When a provider publishes both, we use the 3.x version for more accurate change detection. When only Swagger 2.0 is available, we parse it natively.

Recommendation

Use OpenAPI 3.1 for everything new. Migrate existing Swagger 2.0 specs when you have bandwidth. Don't let the naming confusion slow you down — the tooling works regardless of what it's called.