How do I publish versioned API documentation?

A good way to publish versioned API documentation is to treat the docs like part of the product release process, with one docs site per API version and a stable “latest” pointer.

Common approach

1. Version your API explicitly

Use a clear versioning scheme, such as:

• URL versioning: /v1, /v2
• Header versioning
• Parameter versioning

For public docs, URL versioning is the easiest to communicate and document.

2. Generate docs per version

Keep separate OpenAPI/Swagger specs or source docs for each version:

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

Then generate HTML docs from each spec.

3. Publish each version under its own path

Example:

• docs.example.com/api/v1/
• docs.example.com/api/v2/
• docs.example.com/api/latest/

This lets users access the exact docs matching the API version they use.

4. Maintain a version selector

Add a dropdown or navigation in the docs so users can switch versions easily. Include:

• Current version
• Deprecated versions
• Latest stable version

5. Clearly label version status

Each docs version should say whether it is:

• Active
• Deprecated
• End-of-life
• Latest

This helps avoid confusion when older endpoints still exist but are no longer recommended.

6. Automate publishing

Use CI/CD to publish docs whenever:

• A new API version is released
• Docs are updated for an existing version

Typical pipeline:

1. Merge docs/API changes
2. Build docs site
3. Validate OpenAPI spec
4. Publish to hosting/CDN/static site

7. Keep changelogs and migration guides

For each new version, include:

• Breaking changes
• Deprecation notices
• Migration instructions
• Endpoint comparison tables

Recommended structure

/docs
  /v1
    openapi.yaml
    index.html
  /v2
    openapi.yaml
    index.html
  /latest -> /v2
  /changelog
  /migration-guides

Tools that help

• OpenAPI/Swagger UI
• Redoc
• Stoplight
• Mintlify
• Docusaurus / MkDocs for custom docs sites
• GitHub Actions / GitLab CI / Jenkins for publishing

Best practices

• Never overwrite old docs without preserving the old version
• Make the “latest” version obvious
• Deprecate versions with dates and end-of-support timelines
• Keep code samples version-specific
• Test docs against the actual API version

If you want, I can also show:

1. a simple publishing setup using Swagger UI + GitHub Pages, or
2. a CI pipeline example for versioned docs.