OpenAPI: a machine-readable API contract
Learn what an OpenAPI document describes and why humans, code generators, test tools, and AI clients benefit from the same contract.
Why this matters
An API is much easier to use when its operations, parameters, schemas, authentication, and responses are described consistently instead of scattered across prose pages.
Learn it
OpenAPI is a specification for describing HTTP APIs. A document can define paths, operations, parameters, request bodies, response schemas, security schemes, and reusable components. Tools such as Swagger UI can render an OpenAPI document, but Swagger tooling and the OpenAPI specification are not the same thing. A contract still needs to match the server behavior; documentation does not make an implementation correct by itself.
Work through an example
An operation can describe POST /observations, the required request schema, authentication method, and the possible response codes. A client can inspect that before sending data.
paths:
/observations:
post:
requestBody: …
responses:
'201': …Practice
- 1Find one operation in an OpenAPI document and identify its path, method, request schema, and success response.
- 2Trace a referenced schema into the components section.
- 3Compare the contract with one real request.
What to watch for
Do not call OpenAPI a transport. It describes API behavior; HTTP carries the requests and responses.
Where this takes you
OpenAPI supports API exploration, client generation, validation, testing, integration planning, and safer AI/tool connections.