[Question] Use Swagger `servers` for version prefix and leave the paths as is

[OlegZv]

Subject of the issue

I am trying to figure out how to make Swagger display the version prefix, like /api/latest in the servers list, and the API route excludes that prefix. This way, the swagger UI paths contain only the base paths. So my two questions are:

1. Can this be achieved with the current implementation?
2. Would you consider changing the API to add this functionality?

Your environment

Python 3.11.4
Ubuntu 22.04

Steps to reproduce

Running custom docs example from here: https://github.com/alexschimpf/fastapi-versionizer/blob/main/examples/docs_customization.py

Desired behavior

I'd love to get this as a result. The server contains /v1_0, and all the paths are "base."

I achieved this by changing the _build_version_router to router = APIRouter() (no prefix) and in the versionize changed self._app.include_router(router=version_router, prefix=version_prefix).

Actual behavior

Each version path repeatedly starts with the version prefix /v1_0

[OlegZv]

Something like this: https://github.com/OlegZv/fastapi-versionizer/pull/1

[alexschimpf]

I guess this is nice because you don't get the redundant version prefix for every route in Swagger. I think this can also be done by setting include_version_openapi_route =False and using callback to build the your own OpenAPI routes. Maybe your proposal is better default behavior though.

But what is the difference between setting prefix in the APIRouter constructor vs. setting it via include_router? Not quite understanding what that does.

[schlitzered]

this was the default behavior in 1.0.x releases, i just noticed this because i was updating dependencies, and now 3.0.x is including the route prefix on all endpoints, which is a major bummer.

[alexschimpf]

I went with this new implementation of not using mounted sub-apps because it simplified a lot of things and allowed for more features. I felt it was worth the trade-off of showing redundant version prefixes by default.

Like I said, if you want the old look of versioned Swagger pages (i.e. a server dropdown and routes without version prefixes), you could probably do something like this (although I have not tried):

1. Set include_version_openapi_route = False. This will prevent fastapi-versionizer from creating its own OpenAPI route for each version.
2. Use the callback param to generate your own OpenAPI endpoint for each version that more closely matches that of fastapi-versionizer 1.0.x. It looks like this would involve setting a "servers" field in the OpenAPI spec as well as stripping the version prefix from each path.