Skip to content

About

springdoc-openapi-versioning-demo

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

springdoc-openapi

🔀 API versioning with Spring Framework 7, documented by springdoc-openapi

Spring Boot 4.0 Spring Framework 7 Java 17+ springdoc-openapi 3.0.3 Scalar Swagger UI

📖 springdoc-openapi documentation · 🌱 Spring API versioning · 📦 springdoc-openapi · 🎮 More demos

💖 Sponsored by

Mercedes-Benz    dmTECH    Contrast Security    LVM Versicherung    GDNext

Sponsor on GitHub Support on Open Collective

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. ✨

🧩 What the API returns

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.

🔀 One branch per strategy

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.

⚡ Quick start

You need Java 17+:

git clone https://github.com/springdoc/springdoc-openapi-versioning-demo.git
cd springdoc-openapi-versioning-demo
./mvnw spring-boot:run

Then 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.

🧪 Try it

🏷️ 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'

⚙️ Configure it with properties

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]=version

The 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=version

Note

Use either WebConfig or the properties: remove WebConfig if you configure versioning with properties.

💬 Getting help

🙏 Thanks

Special thanks to the Spring team and JetBrains for their support.

JetBrains logo

About

springdoc-openapi-versioning-demo

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages