English for OpenAPI and Swagger Developers
Vocabulary for developers writing OpenAPI specs — schemas, operations, contract testing, and codegen — for teams discussing API contracts in English.
OpenAPI conversations sit right at the boundary between “what the API actually does” and “what we promised it does,” and most confusion comes from treating the spec as documentation rather than as the contract itself. The vocabulary below is what lets a team say precisely which side of that boundary a bug is on.
The Spec
OpenAPI spec (a.k.a. Swagger spec) — a machine-readable (YAML or JSON) document describing an API’s endpoints, request/response shapes, and authentication, from which docs, clients, and mocks can all be generated.
“Swagger is the older name for the tooling — OpenAPI is the current spec format, and most people use the terms interchangeably now.”
Operation — a single endpoint-plus-method combination in the spec (e.g., GET /users/{id}), with its own parameters, request body, and possible responses defined.
“Add a new operation for this endpoint instead of overloading the existing one with an optional query param that changes its whole response shape.”
Schema — the structural definition of a request or response body’s shape, typically reused across multiple operations via a $ref.
“Don’t duplicate this schema in three places — extract it once and reference it everywhere so a field rename only needs one edit.”
Contract and Codegen
Contract-first design — writing the OpenAPI spec before implementing the endpoint, so the API’s shape is agreed on and reviewable before any code exists.
“We went contract-first on this one — the frontend team started building against the mock server while the backend was still in progress.”
Codegen (code generation) — automatically generating client SDKs, server stubs, or type definitions directly from the spec, so hand-written code can’t drift from the documented contract.
“Regenerate the client from the spec instead of hand-editing the generated file — your fix will get silently overwritten on the next codegen run.”
Contract testing — automated tests that verify an implementation’s actual responses conform to the spec, catching drift between documentation and reality.
“Contract tests caught this — the endpoint stopped returning the
Common Failure Modes
Spec drift — the gradual divergence between what the OpenAPI spec describes and what the API actually does, usually from manual edits to one side without updating the other.
“This isn’t a bug in the client — it’s spec drift. The endpoint changed six months ago and nobody regenerated the docs.”
Breaking change (in an API contract) — a modification (removing a field, changing a type, tightening a required parameter) that would break existing consumers who rely on the previous shape.
“Making that field required is a breaking change for every existing client — bump the API version instead of changing it in place.”
Common Mistakes
- Treating the OpenAPI spec as optional documentation written after the fact, instead of the actual source of truth clients are generated from.
- Hand-editing generated client code instead of fixing the spec and regenerating, which loses the fix on the next codegen run.
- Calling any spec change “just a docs update” without checking whether it’s actually a breaking change for existing consumers.
Practice Exercise
- Explain, in two sentences, the difference between spec drift and a genuine implementation bug.
- Write a short PR comment explaining why a field’s type change in the spec counts as a breaking change.
- Draft a message recommending contract-first design for an upcoming endpoint the frontend team is blocked on.