What is OpenAPI (Swagger)?
A vendor-neutral, machine-readable format (JSON or YAML) for describing HTTP APIs: endpoints, parameters, request and response bodies, and auth. Formerly called the Swagger Specification; 'Swagger' now refers to SmartBear's tools built around it.
Definition
OpenAPI is a standard, language-agnostic format for describing HTTP APIs, usually REST-style APIs. An OpenAPI document, written in YAML or JSON, lists every path and operation (GET /users/{id}, POST /orders), the parameters each takes, the shape of request and response bodies, status codes, authentication schemes and reusable data models. Because the description is machine-readable, tools can generate interactive documentation, client SDKs, server stubs, mock servers, tests and validation from the same file. What is Swagger, and how does it relate to OpenAPI? Swagger began around 2010 to 2011 as a specification and toolset created by Tony Tam at Wordnik. SmartBear acquired Swagger in 2015 and donated the specification to the newly formed OpenAPI Initiative, a Linux Foundation project. The spec was renamed the OpenAPI Specification (OAS): Swagger 2.0 is effectively OpenAPI 2.0, and the first release under the new name was OpenAPI 3.0 in 2017. Since then 'Swagger' refers to tools, mainly Swagger UI, Swagger Editor and Swagger Codegen, while 'OpenAPI' is the specification itself. People still say 'Swagger file' or 'Swagger API' for an API described with OpenAPI, and many frameworks keep 'swagger' in URLs and package names. The main versions you will meet: Swagger/OpenAPI 2.0 uses a top-level swagger: "2.0" field, definitions for models and a single host and basePath. OpenAPI 3.0 introduced components (schemas, parameters, responses, securitySchemes), servers with multiple base URLs, requestBody, callbacks and links. OpenAPI 3.1, released in 2021, made the schema object fully compatible with JSON Schema draft 2020-12, so the same schemas work with ordinary JSON Schema validators; it also added top-level webhooks and allows null as a type instead of the nullable keyword. OpenAPI 3.2, published in 2025, is an incremental update to 3.1. What is Swagger used for in practice? Swagger UI renders an OpenAPI document as interactive documentation where developers can read each endpoint and send test requests from the browser ('Try it out'). Swagger Editor validates the document as you write it. Code generators, most commonly the community-driven OpenAPI Generator (forked from Swagger Codegen in 2018), produce typed clients for TypeScript, Python, Java, Go and dozens of other languages, plus server skeletons. Linters such as Spectral enforce style rules, mock servers such as Prism serve example responses before the backend exists, and API gateways import OpenAPI to configure routes and request validation. There are two ways to produce the document. Code-first: you annotate your code and the framework generates the spec, as FastAPI does automatically, or springdoc-openapi for Spring Boot and Microsoft.AspNetCore.OpenApi or Swashbuckle for ASP.NET Core. Contract-first (design-first): you write the OpenAPI document first, review it with consumers, then generate stubs and clients and implement against it. Contract-first keeps the API design deliberate and lets frontend and backend teams work in parallel; code-first is faster to start and keeps the spec in sync with the implementation automatically.
When to Use OpenAPI (Swagger)
Use OpenAPI for any HTTP API that other people or teams consume: public APIs, partner integrations and internal services with several clients. It gives you documentation that stays close to the truth, generated SDKs instead of hand-written ones, and a contract you can diff in pull requests to catch breaking changes. Pick contract-first when several teams depend on the API or the design needs review before implementation; pick code-first for a single team iterating quickly, but still commit the generated spec and review its diffs. OpenAPI describes request-response HTTP APIs; for GraphQL the schema (SDL) plays the same role, for gRPC it is the Protocol Buffers .proto file, and for event-driven or message-based APIs (Kafka, MQTT, WebSockets) the AsyncAPI specification is the closer fit. For a two-endpoint internal script, a full spec may be more ceremony than it is worth.
OpenAPI (Swagger) in Practice
- A minimal OpenAPI 3.1 document written as JSON (YAML is equally valid and more common): { "openapi": "3.1.0", "info": { "title": "Todo API", "version": "1.0.0" }, "paths": { "/todos/{id}": { "get": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "A todo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } } }, "404": { "description": "Not found" } } } } }, "components": { "schemas": { "Todo": { "type": "object", "required": ["id", "title"], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } } } }
- Code-first with FastAPI: this endpoint automatically appears in the generated spec at /openapi.json, in Swagger UI at /docs and in ReDoc at /redoc. from fastapi import FastAPI app = FastAPI(title="Todo API") @app.get("/todos/{todo_id}") def get_todo(todo_id: int, done: bool | None = None): return {"id": todo_id, "done": done} The type hints become the documented parameters: todo_id as a required integer path parameter and done as an optional boolean query parameter.
- Generating a typed TypeScript client from a spec with OpenAPI Generator: npx @openapitools/openapi-generator-cli generate -i openapi.json -g typescript-fetch -o src/api-client
- Linting a spec in CI with Spectral, failing the build on rule violations: npx @stoplight/spectral-cli lint openapi.yaml
Common Mistakes
- Using 'Swagger' and 'OpenAPI' as competing standards. OpenAPI is the specification (Swagger 2.0 was renamed OpenAPI 2.0); Swagger is now a family of tools that read and write it.
- Mixing 2.0 and 3.x syntax, such as definitions with components or the 3.0 nullable keyword in a 3.1 document. Check the version field and validate the file with a linter.
- Letting the spec drift from the implementation. Generate it from code, or test the running API against the contract in CI, so the documentation does not lie.
- Publishing a spec without examples, descriptions or error responses. Generated clients compile, but consumers still cannot tell what a 422 means or which fields are required.
- Exposing Swagger UI with live credentials on a production host without auth, which can let anyone exercise internal or admin endpoints.
- Assuming a generated client means a stable API. Renaming a schema or an operationId changes generated method names and is a breaking change for SDK users.