git:20260721.412065e to git:20260728.fac4544

14 added, 14 removed. Audit A to A.

---

name: openapi-contracts

description: Drive API development from an OpenAPI spec as the contract, with linting, codegen, and drift detection. Use when building or documenting REST APIs and wanting the spec to be the single source of truth.

---

# OpenAPI contracts

An OpenAPI spec can be the single source of truth for a REST API:

documentation, client and server code, mocks, and tests all derived

from it. The value comes from making the spec the *contract* everything

else is generated from or checked against, not a document written after

the fact and immediately stale.

## Method

1. **Design spec-first for new APIs.** Write the OpenAPI

spec before implementing: it forces the interface

decisions (resources, methods, schemas, errors: see

rest-endpoint-design, api-error-responses) up front,

enables parallel work (frontend against a mock, backend

against the contract), and produces the documentation for

free. Code-first (annotations generating the spec) is

- viable for existing APIs but tends toward implementation-

- shaped rather than consumer-shaped design.

+ viable for existing APIs but tends toward

+ implementation-shaped rather than consumer-shaped design.

2. **Lint the spec for consistency.** A spec linter

(Spectral-class) enforces naming conventions, required

descriptions, error-response coverage, and org-wide rules

(see style-guides for the API): so every endpoint across

- the org is consistent and documented, caught at spec-

- review not after shipping. An unlinted spec drifts into

- inconsistency endpoint by endpoint.

+ the org is consistent and documented, caught at

+ spec-review not after shipping. An unlinted spec drifts

+ into inconsistency endpoint by endpoint.

3. **Generate clients and server stubs from the spec.**

Client SDKs (see api-sdk-design), server request/response

models, and validation from the one spec: so the code

cannot diverge from the contract, and consumers get typed

clients without hand-writing them. This is the payoff of

spec-first: the contract is executable, not aspirational.

4. **Validate requests and responses against the spec at

runtime.** Middleware that checks incoming requests and

outgoing responses conform to the spec (in test/staging

at least): catches the drift where the implementation

quietly stops matching the contract (a field added in

- code but not the spec, or vice versa: see request-

- validation). Contract and implementation staying in sync

- is the whole point; verify it, do not assume it.

+ code but not the spec, or vice versa: see

+ request-validation). Contract and implementation staying

+ in sync is the whole point; verify it, do not assume it.

5. **Detect drift in CI.** Compare the spec against the

- actual API behavior (contract tests: see contract-

- testing) and fail the build on divergence; diff spec

- changes in PRs to catch breaking changes (see api-

- change-management: a removed field or tightened type in

- the spec is a breaking change flagged at review). The

- spec is only a source of truth if drift from it is caught.

+ actual API behavior (contract tests: see contract-testing)

+ and fail the build on divergence; diff spec changes in PRs

+ to catch breaking changes (see api-change-management: a

+ removed field or tightened type in the spec is a breaking

+ change flagged at review). The spec is only a source of

+ truth if drift from it is caught.

6. **Serve the spec as living documentation.** Interactive

docs (Swagger UI / Redoc) generated from the spec, always

matching the real API because it is the same artifact

(see api-reference-docs, docs-as-code): consumers explore

and try endpoints against accurate, current documentation

instead of a hand-written page that lies.

## Boundaries

- Spec-first requires discipline (writing and reviewing the

spec before coding); for a quick internal API with one

consumer it can be overhead, and code-first with

generated docs suffices. Match the ceremony to the API's

reach and consumer count.

- The spec captures structure (endpoints, schemas, types),

not all behavior (business rules, side effects, ordering

guarantees); those still need prose and examples (see

api-reference-docs). The spec is necessary, not

sufficient, documentation.

- GraphQL and gRPC have their own contract mechanisms

(SDL, proto: see graphql-schema-design, grpc-services);

OpenAPI is the REST tool. The contract-first principle

transfers across all three.