# What is OpenAPI Specification?

Also called OpenAPI, Swagger.

The OpenAPI Specification is an open standard for describing HTTP APIs in a machine readable document, written in YAML or JSON. It defines endpoints, parameters, request and response schemas, authentication methods, and examples. Originally named Swagger, it was donated to the OpenAPI Initiative under the Linux Foundation and is now the most widely used API description format.

A single OpenAPI document can drive many artifacts. Interactive documentation, client libraries in numerous languages, server stubs, request validation middleware, mock servers, and contract tests can all be generated from it, which keeps them consistent with one another. Teams adopting a design first workflow write the document before any implementation and treat it as the agreed contract.

Schemas within an OpenAPI document are expressed in a dialect of JSON Schema, so field types, required properties, enumerations, formats, and constraints are described in a form that validators already understand. That overlap is why an OpenAPI description can often be converted into tool definitions for automated callers with little manual work.

The specification has evolved across major versions, with changes to how request bodies, components, and schema dialects are expressed. Tooling support varies by version, so checking that a generator or validator supports the version in use is a practical necessity rather than a formality.

The recurring failure mode is drift. A description maintained by hand alongside the code inevitably diverges from the running service, and a confidently wrong document is worse than none. Generating the document from the implementation, or verifying the implementation against the document in continuous testing, is what keeps it trustworthy.

## Key points

- Machine readable description of an HTTP API in YAML or JSON
- Generates docs, clients, stubs, mocks, and validators
- Schemas use a JSON Schema dialect
- Tooling support differs across major versions
- Must be generated or verified, or it drifts from reality

## In practice

A team writes an OpenAPI document describing an orders endpoint, its query parameters, and the order object schema. From that one file they publish browsable documentation, generate a typed client for the frontend, and add middleware that rejects requests failing schema validation. A contract test in the build compares live responses against the document, so any undocumented change fails before release.

## Related terms

- [API](/en/glossary/api)
- [REST API](/en/glossary/rest-api)
- [JSON Schema](/en/glossary/json-schema)
- [SDK](/en/glossary/sdk)
- [Tool Schema](/en/glossary/tool-schema)

[Back to the AI Glossary](/en/glossary)