Explainer2 min readUpdated August 26, 2026

What is OpenAPI (and Swagger)?

Short answer

OpenAPI is a standard format — written in JSON or YAML — that describes a REST API's paths, methods, parameters, request and response schemas, and servers. Swagger is the older name and the tooling ecosystem built around it. The document lets humans and machines understand an API without reading its source code.

What OpenAPI describes

An OpenAPI document is a single JSON or YAML file that formally describes a REST API. Instead of reading code or scattered docs, a developer — or a tool — can read the spec to learn every endpoint, what it accepts, and what it returns. That machine-readable contract powers documentation sites, client code generators, mock servers, and request validators.

OpenAPI vs Swagger

Swagger was the original name of the specification. In 2015 it was donated to the OpenAPI Initiative and renamed OpenAPI, so the format is now OpenAPI (currently 3.x) while Swagger lives on as the name of popular tooling like Swagger UI and Swagger Editor. In everyday use the terms are often mixed: people say "Swagger file" when they mean an OpenAPI document.

Versions you will seeSwagger 2.0 is the older format; OpenAPI 3.0 and 3.1 are current. OpenAPI 3.1 aligns its schema objects with JSON Schema, which makes request and response definitions more consistent.

The main parts of a document

info — title, version, and description of the API
servers — the base URLs the API is served from
paths — each endpoint, with its HTTP methods and operations
components — reusable schemas, parameters, and security schemes
security — how requests authenticate, such as API keys or OAuth

Try it: OpenAPI ViewerPaste an OpenAPI or Swagger document and inspect paths, methods, servers, and schemas locally.Open tool

Inspecting a spec safely

OpenAPI documents often describe internal or unreleased APIs, so pasting one into a hosted viewer can leak sensitive endpoint details. A local, browser-only viewer parses the document in your tab without uploading it, which lets you scan paths, methods, and schemas while the spec stays on your machine.

References

Questions

Is Swagger the same as OpenAPI?

Effectively yes. Swagger 2.0 was renamed OpenAPI in 2015. Today OpenAPI is the specification and Swagger is the name of the surrounding tools, like Swagger UI and Swagger Editor.

Is an OpenAPI file written in JSON or YAML?

Either. OpenAPI documents can be written in JSON or YAML, and most tools accept both. YAML is common for hand-editing because it is easier to read.

What is an OpenAPI document used for?

It drives generated API documentation, client and server code generation, mock servers, and automated request or response validation, all from one machine-readable source of truth.