Native API Versioning Support (Routing, OpenAPI, Swagger UI)

[raziel057]

Description

API versioning is a critical need in production-grade APIs, especially for long-lived or public APIs that evolve over time. Currently, API Platform requires manual configuration and customization to support versioned APIs (e.g., per-version routing, OpenAPI docs, Swagger UI version switching).

This RFC proposes native support for versioning in API Platform, to reduce boilerplate and improve DX (developer experience) while remaining flexible and non-opinionated.

Use Cases

• Maintain /api/v1/..., /api/v2/... endpoints side-by-side.
• Generate separate OpenAPI specs for each version.
• Offer a version switcher in Swagger UI (using urls[] config).
• Keep non-versioned (default) routes as fallback or entry points.
• Smooth resource evolution with deprecations/migrations.

Current State (Manual Workarounds)

To achieve versioning today, developers must:

• Create multiple resource classes or URI templates manually (e.g., /v1/books, /v2/books).
• Customize OpenApiFactory to generate per-version documentation.
• Override Swagger UI with urls[] to enable a version selector.
• Register custom routes for each version of Swagger/OpenAPI docs.
• Manage version state in controllers, services, etc.
• This works, but is verbose, repetitive, and error-prone.

Proposed Features

1. Versioned Resource Annotation / Attribute

#[ApiVersion('v1')]

3. Version-Aware Routing Loader- Prefix routes automatically based on version (/api/v1/books, etc.)

• Support default version fallbacks (e.g., /api/books => latest or v1)
• Optional: Allow header-based versioning (Accept-Version, etc.)

3. Automatic OpenAPI Documentation Per Version

• Native generation of /docs/v1.json, /docs/v2.json
• Internally reuse and filter resources by version during OpenAPI generation

4. Swagger UI Version Selector
   Update Swagger UI urls[] config automatically to show a version dropdown

swagger:
    versions:
        v1:
            path: /api/docs/v1.json
        v2:
            path: /api/docs/v2.json

Backward Compatibility

• Non-versioned APIs continue to work as-is.
• Versioning is opt-in, so existing projects are unaffected.
• Resource classes without version tags are treated as universal or "latest".

Inspiration from Other Frameworks

• Laravel: Route groups and controller namespaces per version.
• NestJS: Version decorators, per-controller versions.
• Spring Boot: Content negotiation, header or URI versioning.
• FastAPI: Multiple APIRouter instances with prefixes.

Example of UI

Benefits

• Greatly simplifies setup for multi-version APIs
• Reduces boilerplate (no need to override OpenAPI factory or Swagger UI)
• Improves developer onboarding and experience
• Encourages better API lifecycle and evolution practices
• Makes API Platform more attractive for enterprise-grade APIs

Here an example of implementation in ASP.NET Core
https://www.hakantuncer.com/2018/08/05/api-versioning-with-swagger-azure-api-manager-an-introduction/
https://www.youtube.com/watch?v=z4IF8DpcxaM

Would love community feedback and maintainers’ thoughts on feasibility, design direction, and contributions!