asmhatre/spring-boot-demo
1
0
Fork 0
Code Activity

Add openapi-versioning: springdoc-openapi 3.1.1 vs Spring Framework 7 API versioning

Browse Source 
Companion module for "springdoc-openapi with Spring Boot 4.1: Generating,
Customising and Versioning Your API Spec". Reuses the ApiVersionConfigurer
setup from the versioning-mechanics companion project and tests what
springdoc-openapi 3.1.1 actually generates for a path with multiple
version-scoped handlers: a default oneOf-merged operation with an
arbitrary operationId, a working GroupedOpenApi + OpenApiCustomizer fix
that collapses it to one clean schema per version, and a check of the
officially-versioning-supported functional-endpoint path (springdoc
v3.0.2's "Add support for Spring Framework API Versioning with Functional
Endpoints"), which turns out to document only one of two registered
versions rather than either version separately.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01M1uZDXWkY1MnTfQgt4HMeQ
This commit is contained in:
asmhatre
2026-09-17 19:31:42 +00:00
co-authored by Claude Sonnet 5
parent a875bea55a
commit 8d0efb0d4b
26 changed files with 1163 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openapi-versioning/docs/01-versions-and-setup.md
+38
View File
@@ -0,0 +1,38 @@
# Versions and setup
| Component | Version | Source of truth |
|---|---|---|
| Spring Boot | 4.1.1 | `pom.xml` parent |
| Spring Framework | 7.0.9 | resolved transitively by the Boot 4.1.1 BOM |
| springdoc-openapi | 3.1.1 | `pom.xml` property `springdoc.version`; confirmed as the current `<latest>`/`<release>` against Maven Central's `springdoc-openapi-starter-webmvc-ui/maven-metadata.xml` (`lastUpdated` 2026-09-06T16:37:40Z) |
| JDK | 25 (Temurin 25.0.4.1+1) | `java -version` on the build host |
Single dependency beyond the web starter:
```xml
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>3.1.1</version>
</dependency>
```
No other springdoc configuration is required to get `/v3/api-docs` and `/swagger-ui.html` — both
are enabled by default (springdoc logs a `WARN` about this at startup, pointing at
`springdoc.api-docs.enabled=false` / `springdoc.swagger-ui.enabled=false` for production).
## The versioning setup this module builds on
[`WebConfig`](../src/main/java/com/ankurm/openapiversioning/config/WebConfig.java) is the *exact*
`ApiVersionConfigurer` setup from the companion project for [Spring Framework 7 API
Versioning: The Complete Guide](https://ankurm.com/spring-framework-7-api-versioning-guide/):
header-based resolution (`API-Version`), `setVersionRequired(false)`, `setDefaultVersion("1")`.
That article already verified the versioning *mechanics* — baseline handlers, the
supported-versions allow-list, what an unversioned request resolves to. This module deliberately
does not re-litigate any of that; it takes the mechanics as given and asks a narrower question:
once you add springdoc-openapi on top, what actually ends up in the generated spec?
[`AccountController`](../src/main/java/com/ankurm/openapiversioning/web/AccountController.java)
mirrors that article's three-handler shape (`version = "1"`, `"1.1+"`, `"2"`), with one addition:
an `AccountStatus` enum on the v2 response, so the OpenAPI output actually exercises enum
handling, not just flat string fields.