OpenAPI and Swagger are two of the most frequently confused terms in API development. They are related but distinct, and understanding the difference matters for anyone working with REST API documentation.
The relationship between OpenAPI and Swagger
Swagger was originally both a specification format and a set of tools for describing REST APIs, created by SmartBear Software. In 2016, SmartBear donated the Swagger Specification to the OpenAPI Initiative, where it was renamed the OpenAPI Specification (OAS). The tools — Swagger UI, Swagger Editor, Swagger Codegen — retained the Swagger name.
OpenAPI 2.0 vs OpenAPI 3.x
OpenAPI 2.0 is what was previously called Swagger 2.0. OpenAPI 3.0 and 3.1 are the current versions, with significant improvements including better support for callbacks, links, and JSON Schema alignment in 3.1. If you are starting a new API documentation project, use OpenAPI 3.1.
What the OpenAPI Specification defines
An OpenAPI document is a JSON or YAML file that describes a REST API. It defines the API's endpoints, HTTP methods, parameters, request bodies, responses, authentication schemes, and metadata. A complete, accurate OpenAPI document is a machine-readable contract for the API.
Design-first vs code-first approaches
In a design-first approach, the OpenAPI document is the source of truth written before development begins. In a code-first approach, the specification is generated from annotations in the API code. Design-first produces better-designed APIs and better documentation; code-first is faster to get started with.
Tools in the OpenAPI ecosystem
Swagger Editor and Stoplight Studio are popular editing tools. Redoc and Swagger UI render OpenAPI documents as interactive HTML documentation. OpenAPI Generator and Swagger Codegen generate client SDKs and server stubs from OpenAPI documents.
OpenAPI as part of a documentation strategy
An OpenAPI document is a valuable foundation for API documentation, but it is not a complete documentation solution. It covers the reference but not the guides, tutorials, and examples that help developers understand how to use the API to accomplish real tasks.
OpenAPI is the industry standard for describing REST APIs. Used well — as part of a broader documentation strategy that includes guides and examples — it is one of the most effective tools available for improving developer experience.