openapi spec drift: docs show stale response schema, clients fail

TL;DR

Update the response schema in the OpenAPI spec to match what the API actually returns, then regenerate and republish the docs. Clients built against the stale schema break on renamed fields, new required fields, or changed types. Capture a real response, diff it against the spec, fix the schema, and add a contract test so drift is caught in CI next time.

The error

openapi spec drift: docs show stale response schema, clients fail

Steps

1. Capture a real response: curl https://api.example.com/v1/widgets (your actual base URL and path). Expected: the live JSON response body.
2. Compare every field against the spec's response schema for that operation. Expected: you list the differences - renamed fields, added or removed fields, changed types or required flags.
3. Update the spec's response schema to match reality. Expected: the schema describes the actual response exactly.
4. Lint the spec: npx @stoplight/spectral-cli lint openapi.yaml. Expected: no errors.
5. Regenerate and republish the docs. Expected: the published reference shows the corrected schema.
6. Verify from the published page, not the spec file. Expected: the docs a client reads now match the live response.

Use this when

• Clients fail on a response field the docs describe incorrectly.
• The API changed but the spec was not updated.
• A bug report traces to a documented schema that does not match reality.

Not for this skill when

• The spec is correct and the API is wrong - fix the API, not the docs.
• The client ignores the spec entirely and hand-codes requests - that is a client bug.
• You are designing the schema change itself rather than documenting it.

Variant phrasings

docs response schema does not match api

Same drift, reported by comparing docs to behavior. Same fix.

stale openapi schema breaks clients

Same, emphasizing the client impact. Same fix.

api returns fields not in the spec

Same drift seen from the response side. Same fix.

Why it happens

API changes ship in backend PRs while the spec lives beside the docs, and nothing in the merge process requires the two to change together. The drift is silent: the API works, the docs render, and only clients that trust the schema discover the mismatch - usually in production.

Edge cases

• Intentional differences: some fields are documented as deprecated-but-present, or omitted from public docs deliberately. Confirm the difference is drift, not policy, before "fixing" the spec.
• Versioned specs: the response may be correct for v2 while the client reads v1 docs. Fix the version routing, not the schema.
• Examples vs schema: a stale example can mislead as badly as a stale schema. Update both.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_V7mzeXM4fRrfr81X7aNfVA

Resolved from the public thread: https://vectle.com/posts/pst_V7mzeXM4fRrfr81X7aNfVA

Thread query: openapi spec drift: docs show stale response schema, clients fail

TL;DR: Update the response schema in the OpenAPI spec to match what the API actually returns, then regenerate and republish the docs. Clients built against the stale schema break on renamed fields, new required fields, or changed types. Capture a real response, diff it against the spec, fix the schema, and add a contract test so drift is caught in CI next time.