Quick answer: Versioned documentation is only worth its complexity if you actually support multiple live API versions; for a single evolving API, a well-managed deprecation policy with one current spec is cheaper and less error-prone. When true versions are needed, both a docs platform and a spec-branch workflow can do the job, but the source of truth differs: a platform centralizes version rendering in its own cloud, while spec branches keep each version as an OpenAPI file in version control with reviews and history. Choose based on whether you want the docs vendor or the repository to own the version model.
Most teams reach for versioning prematurely. Seeing a version switcher on a polished docs site makes it look like a baseline feature, but maintaining two or more reference sets multiplies every content change and creates a new class of bug where the wrong version describes an endpoint. The honest first question is whether you truly have more than one supported contract at once. Customers pinned to v1 while v2 ships is a genuine case; a single API that changes over time is not, and deprecation headers plus a changelog handle that without parallel docs.
When versioning is genuinely required
Three conditions justify maintaining multiple versions rather than one current spec.
- Supported contracts coexist. v1 remains available with a committed end-of-life while v2 is live, so clients on each need accurate reference.
- Breaking changes cannot be absorbed. External integrators cannot move immediately, so the old contract stays a real target rather than a deprecated alias.
- Behavior differs, not just prose. The versions have distinct schemas or status codes, meaning a single document cannot describe both.
If those do not hold, keep one authoritative spec and use Deprecation and Sunset headers plus a migration guide. That avoids a switcher that mostly creates stale copies.
Platform versioning versus spec branches
When real versions exist, the two approaches encode them differently.
| Dimension | Docs platform versioning | Spec branches / versioned files |
|---|---|---|
| Source of truth | Platform project in cloud | OpenAPI files in git |
| Version switcher | Built in | Generated from branches |
| Review and history | Platform-specific | Normal pull requests |
| Portability | Tied to the platform | Any OpenAPI tool |
| Downstream generation | Limited | Clients and mocks per version |
| Cost model | Subscription tiers | Storage and build time |
How spec branches model versions
A repository-based approach keeps a directory or branch per supported version, each holding a complete OpenAPI document, and generates the reference and the switcher from those files. The mapping between a version and its contract is explicit, and a change to one version is a normal review.
Because the version is a file in source control, the same spec drives generated clients, mocks, and contract tests for that release, rather than the docs platform holding a separate copy that can drift. The migration guide lives next to the contracts it describes.
Keep the end-of-life explicit
Whichever approach you use, treat each version as having a declared lifecycle. Publish the end-of-life date, mark the old version's pages clearly, and use the Sunset header on the API itself so the docs state and the runtime state agree. A version switcher without a retirement plan tends to accumulate ancient copies no one dares delete. If a version is no longer supported, remove it rather than presenting it as a current choice.
Frequently asked questions
Should I add a version switcher before launch?
Only if you will genuinely support more than one live contract. For a single API, a switcher adds maintenance before there is anything to switch between. Start with one spec and a deprecation policy; introduce versioning when a real coexistence need appears.
Can I version just the docs without versioning the API?
You can keep snapshots, but presenting them as parallel versions risks describing contracts that no longer exist. If the goal is history, a changelog and archived snapshots are clearer than a live switcher that implies equal support.
How many versions should I keep?
Only the versions with committed customers and a defined end-of-life, typically one current and one legacy. Each additional version multiplies content and testing cost, so retire old ones on the published schedule rather than keeping them indefinitely.
Does spec branching work with polished docs sites?
Yes. A static reference generator can read the versioned files and produce the same switcher and layout while keeping the OpenAPI documents authoritative in git. The polished output does not require a closed platform to own the version model.
This is part of the Powerduck vs Mintlify comparison — start there for the full decision around API documentation and ownership.
Top comments (0)