Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

OpenAPI vs Swagger: History, Versions and Which to Use

Understand the difference between OpenAPI and Swagger, how the specification evolved from 2.0 to 3.1 and 3.2, and which version you should pick for new work.

Search for API documentation tools and you will meet two names that are used almost interchangeably: OpenAPI and Swagger. They are related but they are not the same thing, and the confusion costs people time when they search for answers or choose a version. This lesson untangles the names and the version numbers.

The short version

  • OpenAPI Specification (OAS) is the standard: the rules for what an API description document looks like. It is maintained by the OpenAPI Initiative, part of the Linux Foundation.
  • Swagger was the original name of the specification. Today "Swagger" is the brand of a family of tools from SmartBear: Swagger UI, Swagger Editor, Swagger Codegen and others.

A handy rule: the format is OpenAPI; Swagger is (mostly) a set of tools that read that format. When someone says "our Swagger file", they almost always mean an OpenAPI document.

A short timeline

timeline
  title From Swagger to OpenAPI
  2011 : Swagger created by Tony Tam at Wordnik
  2014 : Swagger 1.2 widely used
  2014 : Swagger 2.0 released
  2015 : SmartBear donates the spec; OpenAPI Initiative formed
  2017 : OpenAPI 3.0.0
  2021 : OpenAPI 3.1.0 (aligned with JSON Schema)
  2025 : OpenAPI 3.2.0

The specification was renamed OpenAPI when it moved to a vendor-neutral foundation.

Versions you will meet

Version Notes
Swagger 1.2 Old, split across many files. Seen only in legacy projects.
Swagger 2.0 Single document, swagger: "2.0" at the top. Still common in older APIs.
OpenAPI 3.0.x Introduced components, requestBody, servers, oneOf, callbacks and links. The most widely supported 3.x line.
OpenAPI 3.1.x Full alignment with JSON Schema 2020-12, webhooks, type arrays instead of nullable.
OpenAPI 3.2.x Adds features such as support for the QUERY method and richer tag metadata, plus streaming media types. Check your tools before adopting it.

The version is declared in the first field of every document. Notice how the 2.0 key differs from the 3.x key:

YAML
swagger: "2.0"        # Swagger 2.0 documents
openapi: 3.0.3        # OpenAPI 3.0.x documents
openapi: 3.1.0        # OpenAPI 3.1.x documents

What changed from 2.0 to 3.x

The jump from Swagger 2.0 to OpenAPI 3.0 reorganised the document. A tiny sample of the differences:

Concept Swagger 2.0 OpenAPI 3.x
Server address host, basePath, schemes servers list of URLs
Request body a parameter with in: body its own requestBody object
Reusable pieces definitions, parameters, responses everything under components
Content types global consumes / produces per request and response content map
Auth securityDefinitions components.securitySchemes

Spot the version with code

This stand-in reads the first lines of a document and tells you which family it belongs to, which is exactly the first thing every tool does before it chooses a parser.

Python Stand-in: detect the specification version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Which version should you choose?

  1. New project, modern tools: OpenAPI 3.1. It matches JSON Schema, so schemas you write are the same as schemas used elsewhere.
  2. Tool support is limited (some older gateways and generators): OpenAPI 3.0.3 is the safe, universal choice.
  3. Existing Swagger 2.0 files: keep them working, and plan a conversion to 3.x when you next make big changes. Converters exist, and you can review the result by hand.

Check what your generator, gateway and documentation tool support before you start: a document that tools cannot read has little value. This track writes examples in 3.1 and points out where 3.0 differs.

A word on patch versions

The third number (3.0.1, 3.0.2, 3.0.3) only clarifies wording in the specification text. It never changes the format. That is why tools talk about "3.0.x" and why you should treat 3.0.3 the same as 3.0.0 when choosing support.

When you search for help, add the version, for example "OpenAPI 3.1 nullable". Answers written for Swagger 2.0 often do not apply to 3.x.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the best description of the relationship between OpenAPI and Swagger?

    The spec was called Swagger until 2015, then renamed OpenAPI. Swagger now names SmartBear's tools.
  2. 2. Which top-level field marks a Swagger 2.0 document?

    Swagger 2.0 uses the swagger field; OpenAPI 3.x uses openapi.
  3. 3. What is a major improvement in OpenAPI 3.1 over 3.0?

    3.1 made schema objects a superset of JSON Schema 2020-12, which also introduced webhooks.
  4. 4. What does a change from 3.0.2 to 3.0.3 mean?

    Patch versions of the specification never change the format.

Summary

  • OpenAPI is the standard; Swagger was its former name and is now a family of tools.
  • Swagger 2.0 uses swagger: "2.0"; modern documents use openapi: 3.x.y.
  • 3.0 introduced components, requestBody and servers; 3.1 aligned with JSON Schema; 3.2 adds further features.
  • Pick 3.1 for new work if your tools support it, otherwise 3.0.3.

Next: Your first OpenAPI document