How do I document a REST API so it stays updated when endpoints change?

To keep REST API documentation up to date when endpoints change, the key is to reduce manual docs drift and make the docs part of your development workflow.

Best practices

1. Use an API specification as the source of truth

Write your API in a machine-readable format such as:

• OpenAPI/Swagger for REST APIs
• JSON Schema for request/response models

Then generate:

• human-readable docs
• client SDKs
• mock servers
• validation tests

This way, the spec is maintained alongside the code.

2. Keep docs in version control with the code

Store the OpenAPI spec and related documentation in the same repository as the API code.
That makes changes visible in pull requests and easier to review.

3. Enforce docs updates in CI/CD

Add checks so changes to endpoints require matching spec updates:

• validate the OpenAPI file
• compare code routes vs. spec
• fail builds if undocumented endpoints are added or responses change

4. Generate docs from code annotations where possible

If your framework supports it, annotate endpoints, models, and auth requirements in code and generate the spec automatically.
Examples:

• Springdoc for Java/Spring
• Swashbuckle / NSwag for .NET
• FastAPI for Python

5. Use contract tests

Add tests that confirm:

• endpoints documented in OpenAPI still exist
• responses match documented schemas
• deprecated endpoints are still documented correctly

6. Document changes with changelogs and deprecation policy

When endpoints evolve, record:

• what changed
• when it changed
• whether the old version is deprecated
• removal timeline

This helps consumers trust the docs.

7. Automate publishing

Use pipelines to publish docs whenever the spec changes:

• generate Swagger UI / ReDoc pages
• deploy docs with the API release
• tag docs by version

Practical workflow

A solid workflow looks like this:

1. Developer changes endpoint code
2. Update annotations/spec in the same PR
3. CI validates the spec and runs contract tests
4. Docs are generated automatically
5. Release pipeline publishes the updated docs

Recommended setup

If you want the simplest reliable approach:

• Use OpenAPI as the contract
• Generate docs from it
• Validate in CI
• Version your API and docs together

If you want, I can also give you:

• a tooling stack recommendation for your language/framework
• a sample CI pipeline
• or an OpenAPI-first workflow example