How do I stop manual changes from breaking my API docs?

The best way to stop manual changes from breaking your API docs is to make the docs generated from a single source of truth and enforce that in CI.

What to do

1. Generate docs from code or schema

   • Use OpenAPI/Swagger, JSON Schema, gRPC/proto annotations, or framework decorators.
   • Avoid hand-editing published docs whenever possible.

2. Keep docs in the repo, but don’t edit them manually

   • Treat generated docs like build artifacts.
   • If you need custom notes, store them in separate source files/templates that the generator uses.

3. Add validation in CI

   • Run a docs generation step in your pipeline.
   • Fail the build if the generated docs differ from the committed docs.
   • Optionally validate the OpenAPI spec for breaking changes.

4. Automate publishing

   • Regenerate docs on every merge/release.
   • Publish from the built artifact, not from a manually maintained copy.

5. Use contract tests

   • Test that responses match the schema.
   • Test endpoints that docs claim exist actually exist.

Good workflow

• Developer changes API code
• CI generates OpenAPI spec/docs
• CI compares against the checked-in spec/docs
• If there’s a mismatch, the build fails
• Docs get published only from the verified generated output

If you still need manual edits

Use one of these:

• markdown templates + includes
• doc overrides file separate from generated spec
• post-processing step that adds human-written sections after generation

Rule of thumb

If a human edits the final API doc directly, it will drift.
If humans edit the inputs and the docs are generated, drift is much harder.

If you want, I can suggest a setup for your stack (for example: FastAPI, Spring, Express, Django, .NET, or OpenAPI-first).