openapi-contractslisted

# 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. 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. 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