How do I publish versioned API docs for multiple releases?

A good way to publish versioned API docs for multiple releases is to treat documentation like code: generate, tag, and host each release separately, then expose a stable URL pattern for users.

Recommended approach

1. Tie docs to API versions

Use a version identifier that matches your API release strategy, such as:

• v1, v1.1, v2
• date-based versions like 2024-09-01
• semver tags like 1.4.2

Each published docs set should clearly map to one API release.

2. Generate docs per release

For each version, build docs from the corresponding source:

• OpenAPI/Swagger spec
• Markdown docs
• code comments / annotations
• generated SDK references

Example:

• docs/v1/
• docs/v2/

3. Publish each version at its own URL

Use predictable URLs so users can switch versions easily:

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

You can also make the root URL redirect to the newest stable version.

4. Add a version switcher in the UI

If you use a docs portal, include a dropdown or sidebar selector so users can jump between releases quickly.

5. Preserve older versions

Do not overwrite old docs. Keep them available as long as the API version is supported, because users often depend on legacy behavior.

6. Automate publishing in CI/CD

Have your pipeline:

1. detect a release tag
2. generate docs for that version
3. deploy to the correct versioned path
4. update the “latest” alias if appropriate

7. Mark deprecations clearly

In versioned docs, label endpoints as:

• stable
• deprecated
• removed in version X

This helps users know what changes between releases.

---

Common implementation patterns

Option A: Static site per version

Build a separate static site for each version and host them in folders or buckets.

Good for:

• simple deployment
• low maintenance
• archiving old releases

Option B: Single docs app with versioned content

Use one docs application that loads versioned spec/content dynamically.

Good for:

• easier navigation
• unified search
• consistent UI

Option C: OpenAPI-backed docs portal

If your API is described in OpenAPI, many tools support version switching automatically:

• Swagger UI
• Redoc
• Stoplight
• ReadMe
• Docusaurus + OpenAPI plugins

---

Best practices

• Keep a changelog next to each version
• Include a “current version” and “archive” section
• Make unsupported versions clearly labeled as deprecated
• Ensure docs and API versions are released together
• Add canonical links to prevent search engine confusion

---

Example structure

docs.example.com/
  latest/        -> redirects to v3/
  v1/
  v2/
  v3/
  changelog/

Or in a repo:

docs/
  v1/
    openapi.yaml
    index.md
  v2/
    openapi.yaml
    index.md
  v3/
    openapi.yaml
    index.md

---

If you want, I can also show you:

1. a CI/CD workflow for publishing versioned docs, or
2. how to do this with a specific tool like Swagger UI, Redoc, Docusaurus, or GitHub Pages.