Spring Framework 7 - API versioning support

[csterwa]

Spring Framework 7 coming in November 2025

With API versioning support getting into Spring Framework 7, there could be an opportunity to generate multiple OpenAPI specifications for each version that is defined for REST API routes in an application. I'd be interested in talking through solution options if there is interest. Some initial thoughts I've had are:

• Generating a default actuator OpenAPI endpoint but then allow query parameters for different versions
• Exposed API docs endpoint with query parameters, as well
• Add a way to show deprecation of API routes in newer version of OpenAPI generated specification

[bnasslahsen]

@csterwa,

Thank your for your initiative.

It would be great to provide out-of-the-box support for API Versioning.
Ideally, this would allow us to introspect the versioning metadata provided by Spring Framework 7 and automatically expose those versions as REST endpoints/ routes in the OpenAPI specification.

At the moment, I’m not entirely sure what is feasible with the current implementation, as I’m also waiting for more detailed documentation and clarity around how Spring Framework 7 handles versioning internally. Once that becomes available, we’ll have a better foundation to build on.

In the meantime, if you have a solid understanding of the current versioning support, feel free to:

• Start drafting representative test cases (e.g., versioned controllers using annotations or URL pathing)
• Share expected OpenAPI outputs (how each version should be documented and structured)
• Or propose directly a PR

With those examples, we can begin iterating and exploring how to extend or adapt springdoc-openapi accordingly.

Looking forward to collaborating on this!

[csterwa]

Sounds great! As Spring Framework 7 API versioning support gets further along and documentation along with solid test cases are put in place we'll update this issue with more details. I'll start drafting some thoughts up in the meantime. Expect some more comments over the summer.

[rstoyanchev]

Just to mention there is now more detailed documentation. It would be useful to know if there is anything that's perhaps not explained, or could be elaborated on.