OpenAPI, formally the OpenAPI Specification (OAS), is a vendor-neutral, language-independent standard for describing HTTP APIs in a machine-readable document. An OpenAPI document, written in YAML or JSON, lists the endpoints of an API, the operations they accept, their parameters, request and response bodies, status codes and security requirements.
Among APIs, OpenAPI is the dominant description format for REST APIs and other resource-oriented HTTP interfaces. It began as the Swagger Specification and was donated in 2015 to the OpenAPI Initiative under the Linux Foundation. Because the document is precise enough for machines, it acts as a single source of truth from which documentation, client libraries, server stubs, mock servers and tests can be generated.
How an OpenAPI document describes an API
An OpenAPI document is a structured object with fixed top-level fields. The paths object maps each URL template, such as /orders/{orderId}, to the HTTP methods it supports, and each method is described as an operation with parameters, an optional request body and a set of possible responses.
Reusable definitions live in the components section and are referenced with $ref pointers, which keeps large specifications consistent. The table lists the top-level fields of an OpenAPI 3.x document and what each one contains.
| Field | Required | Content |
|---|---|---|
| openapi | Yes | Specification version, for example 3.1.0 |
| info | Yes | Title, API version, description, license |
| servers | No | Base URLs for environments |
| paths | One of paths, webhooks or components | Endpoints and their operations |
| components | No | Reusable schemas, parameters, responses, security schemes |
| security | No | Default authentication requirements |
| tags | No | Groups of operations for documentation |
| webhooks | No, from 3.1 | Requests the API sends to consumers |
Data structures are described with JSON Schema. Since version 3.1, OpenAPI is fully aligned with JSON Schema draft 2020-12, so a schema written for validation elsewhere can be used in an API description without translation. Earlier versions used an extended subset with small but important differences, such as the nullable keyword.
Versions of the specification
The version number in the openapi field determines which features and validation rules apply, and tools often support only some versions. Mixing syntax from different versions is a frequent cause of validation errors.
| Version | Released | Key changes |
|---|---|---|
| Swagger 2.0 | 2014 | Single host and base path, definitions section |
| OpenAPI 3.0 | 2017 | Components, multiple servers, request bodies, callbacks, links |
| OpenAPI 3.1 | 2021 | Full JSON Schema alignment, webhooks, optional paths |
| OpenAPI 3.2 | 2025 | Incremental additions such as more flexible tags and methods |
Many organizations still maintain Swagger 2.0 descriptions because older tooling depends on them. Converters can upgrade a 2.0 document to 3.0 automatically, but the result usually needs manual review of security definitions and file uploads, which changed the most.
OpenAPI compared with other API description formats
OpenAPI is designed for request-response APIs over HTTP. Other API styles use their own contract formats, and choosing the right one depends on the communication model rather than on preference.
| Format | API style | Contract language | Typical use |
|---|---|---|---|
| OpenAPI | REST and HTTP APIs | YAML or JSON with JSON Schema | Public and internal web APIs |
| GraphQL schema | GraphQL | Schema definition language | Flexible client-driven queries |
| Protocol Buffers | gRPC | Proto files | High-performance service calls |
| AsyncAPI | Event-driven messaging | YAML or JSON | Message brokers and streams |
| JSON-RPC description | JSON-RPC | OpenRPC document | Remote procedure calls over JSON |
OpenAPI does not prescribe REST design rules. It can describe a well-designed resource API just as faithfully as a poorly designed one, so a valid description is not proof of a good API. Its value lies in making the contract explicit and testable.
Design-first, code-first and the tooling around OpenAPI
Teams produce OpenAPI documents in one of two ways. In design-first, the description is written and reviewed before implementation, so consumers can comment on the contract early and work against a mock server. In code-first, annotations or framework introspection generate the description from the implementation.
The approaches differ in where errors are caught and how well the description stays current. The table summarizes when each one fits.
| Situation | Recommended approach | Reason |
|---|---|---|
| Public API with external consumers | Design-first | Contract is agreed before code exists |
| Several teams build client and server in parallel | Design-first | Mocks unblock both sides |
| Existing service without documentation | Code-first | Fastest way to an accurate description |
| Small internal API changing daily | Code-first | Description follows the code automatically |
The surrounding tooling is the main reason for adoption. A single document drives interactive documentation, generated client SDKs in many languages, request validation at an API gateway, contract tests in continuous integration and linting against organizational style rules.
Common pitfalls with OpenAPI
The most damaging problem is drift between the description and the real API. A document that no longer matches the implementation misleads consumers and breaks generated clients. Contract tests that validate real responses against the schema are the most reliable defense.
- Missing error responses leave consumers guessing about status codes such as 400, 404 or 429.
- Inline duplicated schemas instead of shared components cause inconsistent models in generated code.
- Overly loose schemas without required fields or formats let invalid data pass validation.
- Breaking changes without a new major version surprise clients that rely on the published contract.
A plain-language summary
OpenAPI is a standard way to write down how a web service can be used. It works like a detailed menu for a restaurant kitchen. It lists every dish you can order, what you must say to order it and exactly what will arrive at your table.
Because the menu follows strict rules, computers can read it too. They can turn it into a readable manual, a test or ready-made code for talking to the service. Everyone works from the same description, so fewer misunderstandings occur.
An example from practice
A regional bank plans a new account information API that a mobile app team and two partner companies will use. Instead of starting with code, the API team writes an OpenAPI 3.1 document describing six endpoints, their JSON Schema models, the OAuth 2.0 security scheme and every error response.
The document is reviewed by the app team and the partners within a week. A mock server generated from it lets the app developers build screens immediately, while the backend team implements the real service. A linter enforces naming rules, and contract tests in the build pipeline compare every real response with the schema.
When the API goes live, the partners generate their client libraries from the same file and integrate in days rather than weeks. Later changes are proposed as edits to the document first, so the contract and the implementation stay in step.