📖 springdoc-openapi documentation · 🌱 Spring API versioning · 📦 springdoc-openapi · 🎮 More demos
If you ❤️ springdoc-openapi, become a sponsor: it covers the project expenses and helps it grow.
Spring Framework 7 brings first-class API versioning:
declare version = "1.0" on a request mapping, tell Spring where to read the version from, and it routes each
request to the right handler. This Spring Boot 4 application shows the four ways to send the version, and how
springdoc-openapi documents every version of the API, in Scalar or Swagger UI. ✨
GET on the users endpoint returns the same users in two shapes:
| Version | Response |
|---|---|
| 1.0 | [{"id":1,"name":"Badr","email":"badr@gmail.com"}]: one name field (UserDTOv1) |
| 2.0 | [{"id":1,"firstName":"Badr","lastName":"","email":"badr@gmail.com"}]: separate name fields (UserDTOv2) |
The version is optional and defaults to 1.0. A version the API does not support gets a 400 Bad Request.
Each branch configures one strategy in WebConfig:
| Strategy | Branch | Configuration | API reference |
|---|---|---|---|
| 🏷️ Media type parameter | main |
useMediaTypeParameter(MediaType.APPLICATION_JSON, "version") |
Scalar at / |
| 🏷️ Media type parameter | media-type |
useMediaTypeParameter(MediaType.APPLICATION_JSON, "version") |
Swagger UI at / |
| 🛣️ Path segment | path-segment |
usePathSegment(1) |
Swagger UI at /swagger-ui.html |
| 📨 Request header | request-header |
useRequestHeader("X-API-Version") |
Scalar at / |
| ❓ Query parameter | request-param |
useQueryParam("version") |
Scalar at / |
A custom ApiVersionParser strips a leading
v from the version, so the path segment v1.0 is read as version 1.0.
You need Java 17+:
git clone https://github.com/springdoc/springdoc-openapi-versioning-demo.git
cd springdoc-openapi-versioning-demo
./mvnw spring-boot:runThen open 👉 http://localhost:8080/ for the Scalar API reference. The OpenAPI description is served at
/v3/api-docs.
To try another strategy, git checkout <branch> and run the application again.
🏷️ Media type parameter (main and media-type branches):
curl -H 'Accept: application/json;version=1.0' http://localhost:8080/api/users/media
curl -H 'Accept: application/json;version=2.0' http://localhost:8080/api/users/media🛣️ Path segment (path-segment branch): the version is the second path segment.
curl http://localhost:8080/api/v1.0/users
curl http://localhost:8080/api/2.0/users📨 Request header (request-header branch):
curl -H 'X-API-Version: 1.0' http://localhost:8080/api/users
curl -H 'X-API-Version: 2.0' http://localhost:8080/api/users❓ Query parameter (request-param branch): this branch names version 2 v2.
curl 'http://localhost:8080/api/users/list?version=1.0'
curl 'http://localhost:8080/api/users/list?version=v2'Instead of WebConfig, Spring Boot can configure API versioning with
spring.mvc.apiversion.* properties.
For the media type strategy of the main branch:
spring.mvc.apiversion.supported=1.0,2.0
spring.mvc.apiversion.default=1.0
spring.mvc.apiversion.required=false
spring.mvc.apiversion.use.media-type-parameter[application/json]=versionThe other strategies use one of these instead of the last line:
spring.mvc.apiversion.use.path-segment=1
spring.mvc.apiversion.use.header=X-API-Version
spring.mvc.apiversion.use.query-parameter=versionNote
Use either WebConfig or the properties: remove WebConfig if you configure versioning with properties.
- 📖 Read the springdoc-openapi documentation and the Spring Framework API versioning reference
- 🙋 Ask questions on Stack Overflow with the
springdoctag - 🐛 Report a problem with this demo in its issues, and a problem with springdoc-openapi itself in its issues
Special thanks to the Spring team and JetBrains for their support.

