How do I get versioned API docs to show the right release?

To make versioned API docs show the correct release, the key is to ensure the docs UI is loading the OpenAPI spec for the same version as the docs route.

Common pattern

If you have routes like:

• /docs/v1
• /docs/v2

then each one should point to a different spec, such as:

• /openapi/v1.json
• /openapi/v2.json

What to check

1. Each version has its own OpenAPI definition

Make sure your app generates separate specs per version, not one shared spec.

Example:

• v1 spec includes only v1 endpoints
• v2 spec includes both v1 and v2 if that’s your API strategy, or only v2 if you split them strictly

2. The docs UI is wired to the right spec URL

In Swagger UI / Redoc / similar, configure the endpoint dynamically based on the version in the URL.

For example:

• /docs/v1 loads /openapi/v1.json
• /docs/v2 loads /openapi/v2.json

3. Your routes and metadata include the version

Set the OpenAPI metadata appropriately:

• title
• version
• servers or base URL if relevant

This helps the UI display the right release name.

4. Cache isn’t serving the wrong spec

If you recently updated docs, a cached spec or browser cache may still show the old release. Try:

• hard refresh
• disabling caching on spec endpoints
• versioning the spec URL itself

5. If using a framework, ensure the version is passed through

Many frameworks let you group routes by version and generate one doc per group. Make sure:

• endpoints are assigned to the correct version group
• docs middleware is configured per group
• the release label matches the route group

Example logic

If the user opens:

• /docs/2.1

your docs page should:

1. detect 2.1
2. request /openapi/2.1.json
3. render the UI with info.version = 2.1

If you’re using Swagger UI

A common fix is to set the spec URL from the request path rather than hardcoding it.

For example:

• parse version from the docs URL
• build the OpenAPI URL dynamically

---

If you tell me what stack you’re using, I can give exact steps for it:

• ASP.NET
• FastAPI
• NestJS
• Spring Boot
• Express
• Django / DRF
• something else