Best way to create versioned docs for a REST API

The best way is usually to keep docs versioned the same way as the API, and make them easy to browse by version and compare across versions.

Recommended approach

1. Version the API explicitly

Use one of these patterns:

• URI versioning: /v1/..., /v2/...
• Header versioning: Accept: application/vnd.yourapi.v1+json
• Query param: ?version=1
  For documentation, URI versioning is the simplest to manage and understand.

2. Maintain a separate docs version per API version

Create docs that match each released API version:

• /docs/v1/
• /docs/v2/
• /docs/latest/ or /docs/current/

Each version should document:

• endpoints
• request/response schemas
• auth
• errors
• deprecations
• breaking changes

3. Use OpenAPI/Swagger as the source of truth

Write and maintain an OpenAPI spec for each version. This gives you:

• machine-readable docs
• client generation
• validation
• interactive UI (Swagger UI / ReDoc)

Typical structure:

• openapi-v1.yaml
• openapi-v2.yaml

4. Automate doc generation and publishing

Generate docs from the OpenAPI spec and publish them in CI/CD:

• build docs on every release
• deploy versioned docs alongside the API release
• keep old docs available for as long as that API version is supported

5. Include changelogs and migration guides

For each new version:

• what changed
• what broke
• how to migrate from prior version
• sunset/end-of-life dates

This is especially important if you have multiple supported versions.

---

Good setup for most teams

A practical setup looks like this:

• OpenAPI spec per version
• Swagger UI or ReDoc for interactive docs
• Versioned docs URLs
• Changelog + migration guide
• Deprecation policy
• CI pipeline to validate and publish docs

---

If you want the simplest maintainable option

Use:

1. OpenAPI
2. /v1 and /v2 in the URL
3. Separate spec file per version
4. Automated doc publishing

That’s usually the cleanest balance of simplicity and long-term maintainability.

If you want, I can also suggest:

• a folder structure for versioned docs,
• a tooling stack,
• or an example for FastAPI / Express / Spring / .NET.