How do I fix API docs that are out of sync with the spec?

To fix API docs that are out of sync with the spec, treat the spec as the source of truth and make the docs follow it.

1. Identify the drift

Compare:

• OpenAPI/Swagger spec vs
• Published docs / rendered examples / SDK docs

Look for differences in:

• endpoints and methods
• request/response schemas
• required/optional fields
• auth requirements
• status codes and error formats
• examples and parameter names

2. Find the source of the mismatch

Common causes:

• docs were edited manually
• spec changed but docs weren’t regenerated
• multiple specs exist and one is stale
• examples in docs are hardcoded
• backend behavior changed without spec update

3. Update the spec first

If behavior changed, update the spec to match the actual API. If the spec is correct and docs are stale, update the docs generation pipeline instead.

4. Regenerate docs from the spec

Prefer automated generation over manual maintenance:

• OpenAPI → Swagger UI / Redoc / static docs
• regenerate SDKs and examples if they are spec-based

5. Fix examples and narratives

Even when generated docs are correct, human-written sections can drift. Update:

• code samples
• cURL snippets
• parameter tables
• auth walkthroughs
• error examples

6. Add validation to prevent recurrence

Add checks in CI/CD:

• spec linting
• doc generation tests
• schema validation against examples
• contract tests for endpoints

7. Establish a single source of truth

Pick one:

• spec-first: update OpenAPI, generate docs/code from it
• code-first: generate spec from code annotations and publish from that pipeline

8. Communicate breaking changes

If the spec changed in a breaking way:

• version the API docs
• mark deprecated fields/endpoints
• provide migration notes

Practical fix flow

1. Compare docs vs spec
2. Decide whether the spec or docs are wrong
3. Correct the source of truth
4. Regenerate docs
5. Validate examples and tests
6. Add CI checks

If you want, I can also give you:

• a step-by-step checklist
• a CI pipeline example
• or a tool-specific approach for OpenAPI/Swagger, Redoc, or Stoplight.